diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 695857feb0..febc315bba 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -270,6 +270,7 @@ * [Global Events Writer Block](guardian/standard-registry/policies/policy-creation/introduction/global-events-writer-block.md) * [Global Events Reader Block](guardian/standard-registry/policies/policy-creation/introduction/global-events-reader-block.md) * [mathBlock](guardian/standard-registry/policies/policy-creation/introduction/mathblock.md) + * [API Execution Payloads](available-policy-workflow-blocks/api-execution-payloads.md) * [Creating Policy using UI](guardian/standard-registry/policies/policy-creation/policy-demo.md) * [Creating a Policy through Policy Configurator](guardian/standard-registry/policies/policy-creation/creating-a-policy-through-policy-configurator/README.md) * [Getting Started with the Policy Workflows](guardian/standard-registry/policies/policy-creation/creating-a-policy-through-policy-configurator/getting-started-with-the-policy-workflows.md) @@ -1053,6 +1054,149 @@ *** +## API Reference + +### Accounts & Profiles + +* [Account APIs](account-apis/README.md) + * [Registering New Account](account-apis/registering-new-account.md) + * [User Login](account-apis/user-login.md) + * [User Session](account-apis/user-session.md) + * [User Listing](account-apis/user-listing-except-root-authority-and-auditor.md) + * [Returns All Root Authorities](account-apis/returns-all-root-authorities.md) + * [Standard Registries Aggregated](account-apis/standard-registries-aggregated.md) + * [User Balance](account-apis/user-balance.md) + * [Change Password](account-apis/change-password.md) + * [Refresh Access Token](account-apis/refresh-access-token.md) +* [Profile APIs](profile-apis/README.md) + * [User Account Information](profile-apis/user-account-information.md) + * [Setting User Credentials](profile-apis/setting-user-credentials.md) + * [Setting User Credentials Asynchronously](profile-apis/setting-user-credentials-asynchronously.md) + * [User Account Balance](profile-apis/user-account-balance.md) + * [Restoring User Profile](profile-apis/restoring-user-profile.md) + * [List Recovery Topics](profile-apis/list-recovery-topics.md) + * [Validate DID Document](profile-apis/validate-did-document.md) + * [Validate DID Keys](profile-apis/validate-did-keys.md) + * [Returns List of Keys](profile-apis/returns-list-of-keys.md) + * [Creates a Key](profile-apis/creates-a-key.md) + * [Deletes a Key](profile-apis/deletes-a-key.md) + +### Settings & Logs + +* [Settings APIs](settings-apis/README.md) + * [Adding Settings](settings-apis/adding-settings.md) + * [Displaying Current Settings](settings-apis/displaying-current-settings.md) + * [Returns Environment Name](settings-apis/returns-environment-name.md) + * [Returns Package Version](settings-apis/returns-package-version.md) +* [Logs APIs](logs-apis/README.md) + * [Returning Logs](logs-apis/returning-logs.md) + * [Returning Log Attributes](logs-apis/returning-log-attributes.md) + * [Returns Seq URL](logs-apis/returns-seq-url.md) + +### Tasks & External + +* [Task APIs](task-apis/README.md) + * [Returning Task Statuses](task-apis/returning-task-statuses.md) +* [External APIs](external-apis/README.md) + * [Sends Data from External Source](external-apis/sends-data-from-external-source.md) + * [Sends Data from External Source (Generic)](external-apis/sends-data-from-external-source-generic.md) + * [Sends Data with Sync Events](external-apis/sends-data-with-sync-events.md) + * [Sends Data with Sync Events (Generic)](external-apis/sends-data-with-sync-events-generic.md) +* [Trustchains APIs](trustchains-apis/README.md) + * [Requesting](trustchains-apis/requesting.md) + * [Building and Returning](trustchains-apis/building-and-returning.md) + +### Tokens + +* [Token APIs](token-apis/README.md) + * [Token Listing](token-apis/token-listing.md) + * [Returns Token by ID](token-apis/returns-token-by-id.md) + * [Token Creation](token-apis/token-listing-1.md) + * [Updating a Token](token-apis/updating-a-token.md) + * [Associates the User with Token](token-apis/associates-the-user-with-token.md) + * [Disassociates the User with Token](token-apis/disassociates-the-user-with-token.md) + * [Grants KYC for the User](token-apis/grants-kyc-for-the-user.md) + * [Revoke KYC of the User](token-apis/revoke-kyc-of-the-user.md) + * [Freeze Tokens of a User](token-apis/freeze-tokens-of-a-user.md) + * [Unfreeze Tokens of a User](token-apis/unfreeze-tokens-of-a-user.md) + * [User Info for Selected Token](token-apis/user-info-for-selected-token.md) +* [Token APIs — Async](token-related-apis-for-asynchronous-execution/README.md) + * [Token Creation](token-related-apis-for-asynchronous-execution/token-creation.md) + * [Updating a Token](token-related-apis-for-asynchronous-execution/updating-a-token.md) + * [Deleting a Token](token-related-apis-for-asynchronous-execution/deleting-a-token.md) + * [Deleting Multiple Tokens](token-related-apis-for-asynchronous-execution/deleting-multiple-tokens.md) + * [Associating User with the Hedera Token](token-related-apis-for-asynchronous-execution/associating-user-with-the-hedera-token.md) + * [Disassociating User with the Hedera Token](token-related-apis-for-asynchronous-execution/disassociating-user-with-the-hedera-token.md) + * [Setting KYC for the User](token-related-apis-for-asynchronous-execution/setting-kyc-for-the-user.md) + * [Unsetting KYC for the User](token-related-apis-for-asynchronous-execution/unsetting-kyc-for-the-user.md) + * [Freezing Tokens of a User](token-related-apis-for-asynchronous-execution/freezing-tokens-of-a-user.md) + * [Unfreezing Tokens of a User](token-related-apis-for-asynchronous-execution/unfreezing-tokens-of-a-user.md) + +### Schemas + +* [Schema Creation APIs](schema-creation-using-the-guardian-apis/README.md) + * [Listing of Schema](schema-creation-using-the-guardian-apis/creation-of-a-schema-1.md) + * [Returning Schema by SchemaID](schema-creation-using-the-guardian-apis/returning-schema-by-schemaid.md) + * [Returns All Schemas Related to the Topic](schema-creation-using-the-guardian-apis/returns-all-schemas-related-to-the-topic.md) + * [Creation of Schema Related to the Topic](schema-creation-using-the-guardian-apis/creation-of-schema-related-to-the-topic.md) + * [Updating Schema](schema-creation-using-the-guardian-apis/updating-schema.md) + * [Deleting a Schema](schema-creation-using-the-guardian-apis/deleting-a-schema.md) + * [Publishing Schema Based on Schema ID](schema-creation-using-the-guardian-apis/publishing-schema-based-on-schema-id.md) + * [Export Schema Message IDs](schema-creation-using-the-guardian-apis/export-a-schema.md) + * [Export Schema as Zip](schema-creation-using-the-guardian-apis/export-a-schema-1.md) + * [Import Schema from IPFS](schema-creation-using-the-guardian-apis/importing-schema-from-ipfs.md) + * [Import Schema from Zip](schema-creation-using-the-guardian-apis/importing-zip-file-containing-schema.md) + * [Schema Preview from IPFS](schema-creation-using-the-guardian-apis/schema-preview-from-ipfs.md) + * [Schema Preview from Zip](schema-creation-using-the-guardian-apis/schema-preview-from-zip.md) +* [System Schema APIs](system-schemas-apis/README.md) + * [Creates New System Schema](system-schemas-apis/creates-new-system-schema.md) + * [Returns Schema by Username](system-schemas-apis/returns-schema-by-username.md) + * [Updates the Schema](system-schemas-apis/updates-the-schema.md) + * [Activates the Schema](system-schemas-apis/publishes-the-schema.md) + * [Delete System Schema](system-schemas-apis/delete-system-schema.md) + * [Returns Schema by Type](system-schemas-apis/returns-schema-by-type.md) + * [Schema Type](system-schemas-apis/schema-type.md) +* [Schema APIs — Async](schema-related-apis-for-asynchronous-execution/README.md) + * [Creation of Schema](schema-related-apis-for-asynchronous-execution/creation-of-schema.md) + * [Publishing Schema](schema-related-apis-for-asynchronous-execution/publishing-schema.md) + * [Importing Schema from IPFS](schema-related-apis-for-asynchronous-execution/importing-schema-from-ipfs.md) + * [Importing Schema from .zip](schema-related-apis-for-asynchronous-execution/importing-schema-from-.zip.md) + * [Previews the Schema from IPFS](schema-related-apis-for-asynchronous-execution/previews-the-schema-from-ipfs.md) + +### Policies + +* [Policy Creation APIs](policy-creation-using-the-guardian-apis/README.md) + * [Prerequisite Steps](policy-creation-using-the-guardian-apis/prerequesite-steps.md) + * [Policy Listing](policy-creation-using-the-guardian-apis/policy-listing.md) + * [Creation of a Policy](policy-creation-using-the-guardian-apis/creation-of-a-policy.md) + * [Retrieves Policy Configuration](policy-creation-using-the-guardian-apis/retrieves-policy-configuration.md) + * [Updates Policy Configuration](policy-creation-using-the-guardian-apis/updates-policy-configuration.md) + * [Publish a Policy](policy-creation-using-the-guardian-apis/publish-a-policy.md) + * [Policy Validation](policy-creation-using-the-guardian-apis/policy-validation.md) + * [Retrieval of Data from Root Policy Block](policy-creation-using-the-guardian-apis/retrieval-of-data-from-root-policy-block.md) + * [Request Block Data](policy-creation-using-the-guardian-apis/request-block-data.md) + * [Sends Data to Specified Block](policy-creation-using-the-guardian-apis/sends-data-to-specified-block.md) + * [Returns Block ID by Tag](policy-creation-using-the-guardian-apis/returns-block-id-by-tag.md) + * [Retrieves Block Data by Tag](policy-creation-using-the-guardian-apis/retrieves-block-data-by-tag.md) + * [Sends Data to Specified Block by Tag](policy-creation-using-the-guardian-apis/sends-data-to-specified-block-by-tag.md) + * [Returns List of Groups of a Particular User](policy-creation-using-the-guardian-apis/returns-list-of-groups-of-a-particular-user.md) + * [Make the Selected Group Active](policy-creation-using-the-guardian-apis/make-the-selected-group-active.md) + * [Export to Zip File](policy-creation-using-the-guardian-apis/export-to-zip-file.md) + * [Exporting Message ID](policy-creation-using-the-guardian-apis/exporting-message-id.md) + * [Import a Policy](policy-creation-using-the-guardian-apis/import-a-policy.md) + * [Import from Zip File](policy-creation-using-the-guardian-apis/import-from-zip-file.md) + * [Policy Preview from IPFS](policy-creation-using-the-guardian-apis/policy-preview-from-ipfs.md) +* [Policy APIs — Async](policy-related-apis-for-asynchronous-execution/README.md) + * [Creates New Policy](policy-related-apis-for-asynchronous-execution/creates-new-policy.md) + * [Publishing a Policy](policy-related-apis-for-asynchronous-execution/publishing-a-policy.md) + * [Importing a Policy from File](policy-related-apis-for-asynchronous-execution/importing-a-policy-from-file.md) + * [Importing a Policy from IPFS](policy-related-apis-for-asynchronous-execution/importing-a-policy-from-ipfs.md) + * [Policy Review](policy-related-apis-for-asynchronous-execution/policy-review.md) + +* [Policy Repository APIs](policy-repository-apis/README.md) + +*** + * [Feedback](feedback/README.md) * [Feedback in Pipelines](feedback/feedback-in-pipelines.md) * [Guardian in Production](guardian-in-production/README.md) diff --git a/docs/account-apis/README.md b/docs/account-apis/README.md new file mode 100644 index 0000000000..d2fd694ca9 --- /dev/null +++ b/docs/account-apis/README.md @@ -0,0 +1,37 @@ +# Account APIs + +The Account APIs handle user registration, authentication, session management, and account queries within the Guardian system. + +**Base URL:** `/api/v1/accounts` + +> **Note:** `POST /accounts/register`, `POST /accounts/login`, and `POST /accounts/access-token` do not require a Bearer token. All other endpoints require `Authorization: Bearer `. + +--- + +## Endpoints + +| Method | Endpoint | Description | Auth Required | +|--------|----------|-------------|---------------| +| **`POST`** | `/accounts/register` | Register a new user account | No | +| **`POST`** | `/accounts/login` | Log in and receive JWT tokens | No | +| **`POST`** | `/accounts/change-password` | Change the authenticated user's password | Yes | +| **`POST`** | `/accounts/access-token` | Refresh access token using a refresh token | No | +| **`GET`** | `/accounts/session` | Return current session information | Yes | +| **`GET`** | `/accounts/` | List users (excluding Standard Registry and Auditor) | Yes | +| **`GET`** | `/accounts/standard-registries` | Return all Standard Registry accounts | Yes | +| **`GET`** | `/accounts/standard-registries/aggregated` | Return Standard Registries with policies and VCs | Yes | +| **`GET`** | `/accounts/balance` | Return the authenticated user's Hedera balance | Yes | + +--- + +## Endpoint Details + +* [Registering a New Account](registering-new-account.md) +* [User Login](user-login.md) +* [Change Password](change-password.md) +* [Refresh Access Token](refresh-access-token.md) +* [User Session](user-session.md) +* [User Listing (Excluding Standard Registry and Auditor)](user-listing-except-root-authority-and-auditor.md) +* [Returns All Standard Registries](returns-all-root-authorities.md) +* [Standard Registries Aggregated](standard-registries-aggregated.md) +* [User Balance](user-balance.md) diff --git a/docs/account-apis/change-password.md b/docs/account-apis/change-password.md new file mode 100644 index 0000000000..87b75484a2 --- /dev/null +++ b/docs/account-apis/change-password.md @@ -0,0 +1,52 @@ +# Change Password + +**`POST /accounts/change-password`** + +Changes the authenticated user's password. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +--- + +## Request + +### Request Body + +```json +{ + "username": "example_user", + "oldPassword": "examplePassword123", + "newPassword": "newSecurePassword456" +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `username` | string | Yes | The account username | +| `oldPassword` | string | Yes | The current password | +| `newPassword` | string | Yes | The new password to set | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "username": "example_user", + "role": "STANDARD_REGISTRY", + "did": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", + "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Invalid credentials or missing token | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/account-apis/refresh-access-token.md b/docs/account-apis/refresh-access-token.md new file mode 100644 index 0000000000..44426bd8d8 --- /dev/null +++ b/docs/account-apis/refresh-access-token.md @@ -0,0 +1,41 @@ +# Refresh Access Token + +**`POST /accounts/access-token`** + +Returns a new access token using a valid refresh token. + +--- + +## Request + +### Request Body + +```json +{ + "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `refreshToken` | string | Yes | A valid refresh token obtained from login | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Invalid or expired refresh token | diff --git a/docs/account-apis/registering-new-account.md b/docs/account-apis/registering-new-account.md index 105050e9dd..762432d687 100644 --- a/docs/account-apis/registering-new-account.md +++ b/docs/account-apis/registering-new-account.md @@ -1,35 +1,53 @@ -# Registering new account +# Registering a New Account -### REGISTERING NEW ACCOUNT +**`POST /accounts/register`** -{% swagger method="post" path="" baseUrl="/accounts/register" summary="Registers a new user account" %} -{% swagger-description %} +Registers a new user account with a username, password, and optional role. -{% endswagger-description %} +**Authentication:** Bearer token required for non-demo mode (`Authorization: Bearer `). Only a Standard Registry user may register new accounts outside of demo mode. -{% swagger-parameter in="body" required="true" %} -Object that contain username, password and role (optional) fields -{% endswagger-parameter %} +--- -{% swagger-response status="201: Created" description="Successful Operation" %} -```javascript +## Request + +### Request Body + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Account' + "username": "example_user", + "password": "examplePassword123", + "role": "USER" } ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `username` | string | Yes | The new account username | +| `password` | string | Yes | The account password | +| `role` | string | No | User role: `STANDARD_REGISTRY`, `USER`, or `AUDITOR`. Defaults to `USER` | + +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "username": "example_user", + "role": "USER", + "did": null, + "hederaAccountId": null } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Caller is not authenticated (non-demo mode) | +| `403 Forbidden` | Caller does not have Standard Registry role | +| `409 Conflict` | Username already exists | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/account-apis/returns-all-root-authorities.md b/docs/account-apis/returns-all-root-authorities.md index 9059dbf2eb..31720741a7 100644 --- a/docs/account-apis/returns-all-root-authorities.md +++ b/docs/account-apis/returns-all-root-authorities.md @@ -1,39 +1,44 @@ -# Returns all Standard Registries - -{% swagger method="get" path="" baseUrl="/accounts/standard-registries" summary="Returns an array of Standard Registries for user to select one during registration process" %} -{% swagger-description %} -Returns all Standard Registries -{% endswagger-description %} - -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/Account' -} -``` -{% endswagger-response %} +# Returns All Standard Registries -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} - -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} +**`GET /accounts/standard-registries`** + +Returns all Standard Registry accounts available in the system. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.ACCOUNTS_STANDARD_REGISTRY_READ` + +--- + +## Request + +No request body or parameters required. + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +[ + { + "username": "registry_user", + "role": "STANDARD_REGISTRY", + "did": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "hederaAccountId": "0.0.4532001", + "confirmed": true, + "failed": false + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/account-apis/standard-registries-aggregated.md b/docs/account-apis/standard-registries-aggregated.md new file mode 100644 index 0000000000..b5ccf7028a --- /dev/null +++ b/docs/account-apis/standard-registries-aggregated.md @@ -0,0 +1,54 @@ +# Standard Registries Aggregated + +**`GET /accounts/standard-registries/aggregated`** + +Returns all Standard Registry accounts aggregated with their associated policies and VC documents. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.ACCOUNTS_STANDARD_REGISTRY_READ` + +--- + +## Request + +No request body or parameters required. + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +[ + { + "did": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "username": "registry_user", + "hederaAccountId": "0.0.4532001", + "vcDocument": { + "@context": ["https://www.w3.org/2018/credentials/v1"], + "id": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "type": ["VerifiableCredential"] + }, + "policies": [ + { + "id": "63e3e5e8a01b3c001234abcd", + "name": "Example Policy", + "version": "1.0.0", + "status": "PUBLISH" + } + ] + } +] +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/account-apis/user-balance.md b/docs/account-apis/user-balance.md index 35aa13ea6a..c32597e79b 100644 --- a/docs/account-apis/user-balance.md +++ b/docs/account-apis/user-balance.md @@ -1,42 +1,42 @@ # User Balance -### RETURNS CURRENT USER'S HEDERA ACCOUNT BALANCE +**`GET /accounts/balance`** -{% swagger method="get" path="" baseUrl="/accounts/balance" summary="Returns user's Hedera account balance" %} -{% swagger-description %} -Requests current Hedera account balance -{% endswagger-description %} +Returns the authenticated user's current Hedera account balance. -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - type: object - properties: - balance: - type: number - unit: - type: string - user: - type: object - properties: - username: - type: string - did: - type: string -} -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.PROFILES_BALANCE_READ` + +--- + +## Request + +No request body or parameters required. -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: + "balance": 9.26, + "unit": "Hbar", + "user": { + "username": "example_user", + "did": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001" + } } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/account-apis/user-listing-except-root-authority-and-auditor.md b/docs/account-apis/user-listing-except-root-authority-and-auditor.md index 527a51e1a2..719ea33cdb 100644 --- a/docs/account-apis/user-listing-except-root-authority-and-auditor.md +++ b/docs/account-apis/user-listing-except-root-authority-and-auditor.md @@ -1,49 +1,44 @@ -# User listing except Standard Registry and Auditor - -### DISPLAYING USERS - -{% swagger method="get" path="" baseUrl="/accounts" summary="Returns a list of users, excluding Standard Registry and Auditors" %} -{% swagger-description %} -Returns all users except those with roles Standard Registry and Auditor. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} - -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/Account' -} -``` -{% endswagger-response %} +# User Listing (Excluding Standard Registry and Auditor) -{% swagger-response status="401: Unauthorized" description="" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +**`GET /accounts/`** -{% swagger-response status="403: Forbidden" description="" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} - -{% swagger-response status="500: Internal Server Error" description="" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} +Returns a list of all user accounts, excluding those with Standard Registry and Auditor roles. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.ACCOUNTS_ACCOUNT_READ` + +--- + +## Request + +No request body or parameters required. + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +[ + { + "username": "example_user", + "role": "USER", + "did": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "hederaAccountId": "0.0.4532001", + "confirmed": true, + "failed": false + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/account-apis/user-login.md b/docs/account-apis/user-login.md index e47a094358..273f8cbc40 100644 --- a/docs/account-apis/user-login.md +++ b/docs/account-apis/user-login.md @@ -1,35 +1,48 @@ # User Login -### LOGS USER INTO THE SYSTEM +**`POST /accounts/login`** -{% swagger method="post" path="" baseUrl="/accounts/login" summary="Logs user into the system" %} -{% swagger-description %} +Logs a user into the system and returns a session with access and refresh tokens. -{% endswagger-description %} +--- -{% swagger-parameter in="body" required="true" %} -Object that contains username and password fields -{% endswagger-parameter %} +## Request -{% swagger-response status="200: OK" description="" %} -```javascript +### Request Body + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Session' + "username": "example_user", + "password": "examplePassword123" } ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="" %} -```javascript +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `username` | string | Yes | The account username | +| `password` | string | Yes | The account password | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "username": "example_user", + "role": "STANDARD_REGISTRY", + "did": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", + "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Invalid username or password | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/account-apis/user-session.md b/docs/account-apis/user-session.md index b56500a013..532d9dfd5d 100644 --- a/docs/account-apis/user-session.md +++ b/docs/account-apis/user-session.md @@ -1,47 +1,39 @@ # User Session -### DISPLAY CURRENT USER SESSION +**`GET /accounts/session`** -{% swagger method="get" path="" baseUrl="/accounts/session" summary="Returns current session of the user" %} -{% swagger-description %} -Returns current user session -{% endswagger-description %} +Returns the current session information for the authenticated user. -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Session' -} -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request + +No request body or parameters required. + +--- + +## Response -{% swagger-response status="500: Internal Server Error" description="" %} -```javascript +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "username": "example_user", + "role": "STANDARD_REGISTRY", + "did": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "hederaAccountId": "0.0.4532001", + "permissionsGroup": [], + "permissions": [] } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/available-policy-workflow-blocks/api-execution-payloads.md b/docs/available-policy-workflow-blocks/api-execution-payloads.md new file mode 100644 index 0000000000..dfe7071952 --- /dev/null +++ b/docs/available-policy-workflow-blocks/api-execution-payloads.md @@ -0,0 +1,639 @@ +# Policy Block API Execution Payloads + +This guide documents how external systems interact with Guardian policy blocks through the REST API. It is the primary reference for integrators building MRV data pipelines, verification systems, or any application that submits data into a Guardian policy. + +## Overview + +A Guardian policy is a directed graph of blocks. External systems interact with blocks through three patterns: + +| Pattern | Method | URL | When to use | +|---|---|---|---| +| Read block state | GET | `/api/v1/policies/{policyId}/blocks/{blockId}` | Get current form schema, document list, or block UI state | +| Submit data | PUT | `/api/v1/policies/{policyId}/blocks/{blockId}` | Submit a form, trigger a button, select a role | +| Push external data | POST | `/api/v1/external/{policyId}/{blockTag}` | Push MRV/oracle data without a Guardian user session | + +## Authentication + +All block API calls require a JWT Bearer token from `POST /api/v1/accounts/login`. + +```http +Authorization: Bearer +``` + +The calling user must have been assigned the appropriate role within the policy. + +--- + +## Standard Block Response Envelope + +When calling `GET /policies/{policyId}/blocks/{blockId}`, Guardian returns a block-specific response. All responses share these common fields: + +| Field | Type | Description | +|---|---|---| +| id | string | Block UUID | +| blockType | string | Block type identifier from `BlockType` enum | +| policyId | string | Owning policy ID | +| readonly | boolean | Whether the calling user can submit data to this block | +| uiMetaData | object | Block-specific display configuration (title, description, type) | + +--- + +## Block-Specific Payloads + +### `requestVcDocumentBlock` + +Presents a data entry form based on a schema. The user fills the form and submits a VC document. + +**GET response — block state:** + +```json +{ + "id": "block-uuid", + "blockType": "requestVcDocumentBlock", + "uiMetaData": { + "type": "page", + "title": "Installer Registration", + "description": "Fill in your facility details" + }, + "schema": { + "$id": "#installer-schema-uuid", + "title": "Installer Application", + "type": "object", + "properties": { + "field0": { "title": "Organization Name", "type": "string" }, + "field1": { "title": "Country", "type": "string" }, + "field2": { "title": "Facility Name", "type": "string" }, + "field3": { "title": "Installed Capacity (MW)", "type": "number" } + }, + "required": ["field0", "field1", "field2"] + }, + "presetSchema": null, + "presetFields": [] +} +``` + +**PUT request — submit document:** + +```json +{ + "document": { + "credentialSubject": [ + { + "type": "#installer-schema-uuid", + "field0": "Acme Energy Corp", + "field1": "Kenya", + "field2": "Nairobi Solar Farm 1", + "field3": 10.5 + } + ] + }, + "ref": null +} +``` + +| Field | Type | Required | Description | +|---|---|---|---| +| document | object | Yes | VC document to submit | +| document.credentialSubject | array | Yes | Array with one object containing schema-defined fields | +| ref | string | No | Parent document ID for relationship linking | + +--- + +### `uploadVcDocumentBlock` + +Accepts file uploads or pre-built VC documents. + +**PUT request:** + +```json +{ + "document": { + "credentialSubject": [ + { + "type": "#mrv-schema-uuid", + "field0": 0.0, + "field1": 1250.5, + "field2": "MWh", + "field3": "2025-01-01", + "field4": "2025-12-31" + } + ] + } +} +``` + +--- + +### `interfaceDocumentsSourceBlock` + +Displays a list of documents to the user. Read-only; no PUT required. + +**GET response:** + +```json +{ + "id": "block-uuid", + "blockType": "interfaceDocumentsSourceBlock", + "data": [ + { + "id": "doc-id-123", + "type": "VC", + "owner": "did:hedera:testnet:...", + "document": { ... }, + "option": { "status": "WAITING" }, + "createDate": "2026-03-31T08:00:00.000Z" + } + ], + "fields": [ + { "title": "Status", "name": "option.status", "type": "text" }, + { "title": "Created", "name": "createDate", "type": "date" } + ], + "total": 1, + "page": 0, + "size": 10 +} +``` + +--- + +### `buttonBlock` + +Displays action buttons that trigger workflow transitions (e.g., Approve/Reject). + +**GET response:** + +```json +{ + "id": "block-uuid", + "blockType": "buttonBlock", + "uiMetaData": { + "buttons": [ + { + "tag": "approve_btn", + "name": "Approve", + "type": "selector", + "field": "option.status", + "value": "APPROVED", + "uiClass": "btn-approve" + }, + { + "tag": "reject_btn", + "name": "Reject", + "type": "selector", + "field": "option.status", + "value": "REJECTED", + "uiClass": "btn-reject" + } + ] + } +} +``` + +**PUT request — trigger a button:** + +```json +{ + "document": { + "id": "doc-id-123", + "option": { "status": "WAITING" } + }, + "tag": "approve_btn" +} +``` + +| Field | Type | Required | Description | +|---|---|---|---| +| document | object | Yes | The document to act on (must include `id`) | +| tag | string | Yes | Button tag to trigger — must match one of `uiMetaData.buttons[].tag` | + +--- + +### `policyRolesBlock` + +Assigns a role to the current user within the policy. + +**GET response:** + +```json +{ + "id": "block-uuid", + "blockType": "policyRolesBlock", + "uiMetaData": { "title": "Select Your Role" }, + "roles": ["Installer", "Standard Registry", "Auditor"] +} +``` + +**PUT request — select role:** + +```json +{ + "role": "Installer" +} +``` + +| Field | Type | Required | Description | +|---|---|---|---| +| role | string | Yes | Role name — must be one of the values in the GET response `roles` array | + +--- + +### `mintDocumentBlock` + +Mints environmental asset tokens after document approval. This is a server-side block (`post: false`, `get: false`) — it is triggered automatically by the policy engine when an upstream block fires a `RunEvent`. There is no direct GET or PUT available from the API. + +The block calculates a token amount by evaluating the configured rule expression against the incoming VC documents, creates a mint VC and VP, publishes both to HCS, and calls the Hedera token service to mint the tokens to the target account. + +To observe mint outcomes, query the `interfaceDocumentsSourceBlock` that follows the mint block in the policy flow — documents there will carry a `type` of `"MINT"` once minting completes. + +--- + +### `retirementDocumentBlock` + +Retires (wipes) tokens from a holder account. This is a server-side block (`post: false`, `get: false`) — it is triggered automatically by the policy engine when an upstream block fires a `RunEvent`. There is no direct GET or PUT available from the API. + +The block evaluates the configured rule expression (fungible tokens) or serial number expression (non-fungible tokens) against the incoming VC documents, creates a wipe VC and VP, publishes both to HCS, and calls the Hedera token wipe service. + +--- + +### `createTokenBlock` + +Presents a token configuration form that allows a user to define and create a new Hedera token within the policy's token template. The block can also be set to `autorun`, in which case it creates the token automatically without user interaction. + +**GET response — token template:** + +```json +{ + "id": "block-uuid", + "blockType": "createTokenBlock", + "title": "Create Token", + "description": "Define the token parameters", + "data": { + "tokenName": "iREC Token", + "tokenSymbol": "iREC", + "tokenType": "fungible", + "decimals": "2", + "initialSupply": "0", + "enableAdmin": true, + "changeSupply": true, + "enableFreeze": false, + "enableKYC": false, + "enableWipe": true, + "wipeContractId": null + } +} +``` + +Fields already locked by the policy template will be returned in `data` but cannot be overridden in the PUT — submit only the fields the policy leaves editable. + +**PUT request — submit token configuration:** + +```json +{ + "tokenName": "iREC Token", + "tokenSymbol": "iREC", + "tokenType": "fungible", + "decimals": "2", + "initialSupply": "0", + "enableAdmin": true, + "changeSupply": true, + "enableFreeze": false, + "enableKYC": false, + "enableWipe": true, + "wipeContractId": null +} +``` + +| Field | Type | Description | +|---|---|---| +| tokenName | string | Human-readable token name | +| tokenSymbol | string | Short token symbol (e.g. `"iREC"`) | +| tokenType | string | `"fungible"` or `"non-fungible"` | +| decimals | string | Decimal precision for fungible tokens (e.g. `"2"`) | +| initialSupply | string | Initial supply for fungible tokens (e.g. `"0"`) | +| enableAdmin | boolean | Enables admin key on the token | +| changeSupply | boolean | Enables supply key (required for minting) | +| enableFreeze | boolean | Enables freeze key | +| enableKYC | boolean | Enables KYC key | +| enableWipe | boolean | Enables wipe key (required for retirement) | +| wipeContractId | string \| null | Optional Hedera contract ID to use as wipe key | + +On success the block publishes the new token to HCS, stores the resulting `tokenId` in the policy document's `tokens` map, and fires a `RunEvent` to the next block. + +--- + +### `tokenConfirmationBlock` + +Prompts the current user to associate (or dissociate) their Hedera account with a specific token, or to skip the step. This is required before a user can receive minted tokens. + +**GET response:** + +```json +{ + "id": "block-uuid", + "blockType": "tokenConfirmationBlock", + "action": "associate", + "accountId": "0.0.1234567", + "tokenName": "iREC Token", + "tokenId": "0.0.9876543" +} +``` + +| Field | Type | Description | +|---|---|---| +| action | string | `"associate"` or `"dissociate"` — the operation the user is being asked to confirm | +| accountId | string | The user's Hedera account ID that will be associated | +| tokenName | string | Display name of the token | +| tokenId | string | Hedera token ID to associate | + +**PUT request — confirm association:** + +```json +{ + "action": "confirm", + "hederaAccountKey": "302e020100300506032b657004220420..." +} +``` + +**PUT request — skip:** + +```json +{ + "action": "skip" +} +``` + +| Field | Type | Required | Description | +|---|---|---|---| +| action | string | Yes | `"confirm"` to proceed with the association/dissociation, `"skip"` to bypass | +| hederaAccountKey | string | Only when `action` is `"confirm"` | The user's Hedera ED25519 private key (hex or DER-encoded) used to sign the association transaction | + +> **Security note:** `hederaAccountKey` is transmitted over HTTPS and used in-process to sign the Hedera association transaction. It is not stored by Guardian. + +--- + +### `externalDataBlock` + +Receives data pushed from external systems. This is the block to target with `POST /external/{policyId}/{blockTag}`. + +**GET response:** + +```json +{ + "id": "block-uuid", + "blockType": "externalDataBlock", + "tag": "mrv_data_ingestion" +} +``` + +**External push via** `POST /api/v1/external/{policyId}/{blockTag}`: + +```json +{ + "owner": "did:hedera:testnet:zHcDLGFNTnbmDMkaGEfb5zToJKj4KdwNPJ5mGFNjrEV", + "policyTag": "iREC_V3_Installer", + "document": { + "@context": ["https://www.w3.org/2018/credentials/v1"], + "type": ["VerifiableCredential"], + "issuer": "did:hedera:testnet:...", + "issuanceDate": "2026-03-31T00:00:00.000Z", + "credentialSubject": [ + { + "type": "#mrv-schema-uuid", + "field0": 0.0, + "field1": 1250.5, + "field2": "MWh", + "field3": "2025-01-01", + "field4": "2025-12-31" + } + ] + } +} +``` + +| Field | Type | Required | Description | +|---|---|---|---| +| owner | string | Yes | DID of the document submitter | +| policyTag | string | Yes | Policy tag string (from policy configuration) | +| document | object | Yes | Full or partial VC document | +| document.credentialSubject | array | Yes | Array containing one credential subject with schema fields | + +--- + +### `reportBlock` + +Generates a trust chain / audit trail view. Read-only. + +**GET response:** + +```json +{ + "id": "block-uuid", + "blockType": "reportBlock", + "uiMetaData": { "title": "Trust Chain Report" }, + "items": [ + { + "title": "Registration Document", + "document": { ... }, + "type": "VC", + "tag": "installer_registration", + "issuer": "did:hedera:testnet:..." + }, + { + "title": "MRV Report", + "document": { ... }, + "type": "VC", + "tag": "mrv_submission" + }, + { + "title": "Minted Token", + "tokenId": "0.0.1234567", + "amount": 1250, + "type": "TOKEN" + } + ] +} +``` + +--- + +### `switchBlock` + +Routes documents to different workflow paths based on conditions. Evaluated automatically by the policy engine — no external interaction required. + +--- + +### `aggregateDocumentBlock` + +Collects multiple documents until a threshold is met, then batches them. Evaluated automatically. + +--- + +### `calculateContainerBlock` / `mathBlock` + +Performs arithmetic on document fields. Evaluated automatically. + +--- + +### `sendToGuardianBlock` + +Sends a document to the Hedera blockchain (IPFS + HCS). Evaluated automatically after form submission or approval. + +--- + +## External Data Submission API Reference + +### POST /api/v1/external/{policyId}/{blockTag} + +The primary integration endpoint for external MRV systems, IoT sensors, and oracles. + +**Authentication:** Not required for `externalDataBlock` configured as public. JWT required otherwise. + +**Path Parameters:** + +| Parameter | Type | Required | Description | +|---|---|---|---| +| policyId | string | Yes | Policy MongoDB ID or published policy message ID | +| blockTag | string | Yes | Unique tag of the target `externalDataBlock` | + +**Full Request Body Schema:** + +```json +{ + "owner": "string — DID of document owner (required)", + "policyTag": "string — policy tag identifier (required)", + "document": { + "@context": ["array of JSON-LD context URLs"], + "type": ["VerifiableCredential"], + "issuer": "string — DID of issuer", + "issuanceDate": "string — ISO 8601 date", + "credentialSubject": [ + { + "type": "string — schema type IRI", + "field0": "value matching schema field type", + "field1": "...", + "fieldN": "..." + } + ], + "proof": { + "type": "string", + "created": "string", + "verificationMethod": "string", + "proofPurpose": "string", + "jws": "string" + } + } +} +``` + +The `proof` field is optional — Guardian will sign the document if not provided. + +**Response 200 OK:** +```json +true +``` + +**Error Codes:** + +| Code | Description | +|---|---| +| 400 | Missing required fields | +| 404 | Policy or block tag not found | +| 422 | Document validation failed against policy schema | +| 500 | Internal server error | + +--- + +## Tag-Based Block Access + +Blocks can also be accessed by tag name instead of UUID: + +``` +GET /api/v1/policies/{policyId}/tag/{tagName}/blocks +PUT /api/v1/policies/{policyId}/tag/{tagName}/blocks +``` + +This is useful when block UUIDs change between policy versions but tags remain stable. + +--- + +## Complete Integration Workflow + +### Step 1 — Authenticate + +```http +POST /api/v1/accounts/login +Content-Type: application/json + +{ "username": "mrv_provider", "password": "securepassword" } +``` + +```json +{ "accessToken": "eyJhbGciOiJSUzI1NiJ9...", "did": "did:hedera:testnet:..." } +``` + +### Step 2 — Find Published Policy + +```http +GET /api/v1/policies?pageIndex=0&pageSize=10 +Authorization: Bearer eyJhbGciOiJSUzI1NiJ9... +``` + +Locate the policy by `name` or `policyTag` in the response. Note its `id`. + +### Step 3 — Navigate to Roles Block + +```http +GET /api/v1/policies/{policyId}/navigation +Authorization: Bearer eyJhbGciOiJSUzI1NiJ9... +``` + +Find the `policyRolesBlock` in the block tree. Note its `id`. + +### Step 4 — Select Role + +```http +PUT /api/v1/policies/{policyId}/blocks/{rolesBlockId} +Authorization: Bearer eyJhbGciOiJSUzI1NiJ9... +Content-Type: application/json + +{ "role": "MRV Submitter" } +``` + +### Step 5 — Get Submission Form Schema + +```http +GET /api/v1/policies/{policyId}/blocks/{formBlockId} +Authorization: Bearer eyJhbGciOiJSUzI1NiJ9... +``` + +Extract the `schema.properties` to determine which fields to populate. + +### Step 6 — Submit Document + +```http +PUT /api/v1/policies/{policyId}/blocks/{formBlockId} +Authorization: Bearer eyJhbGciOiJSUzI1NiJ9... +Content-Type: application/json + +{ + "document": { + "credentialSubject": [ + { + "type": "#schema-uuid", + "field0": 0.0, + "field1": 1250.5, + "field2": "MWh" + } + ] + } +} +``` + +### Step 7 — Poll Document Status + +```http +GET /api/v1/policies/{policyId}/blocks/{viewerBlockId} +Authorization: Bearer eyJhbGciOiJSUzI1NiJ9... +``` + +Poll until `data[0].option.status` changes to `APPROVED` or `REJECTED`. diff --git a/docs/external-apis/README.md b/docs/external-apis/README.md new file mode 100644 index 0000000000..6d0d3b483a --- /dev/null +++ b/docs/external-apis/README.md @@ -0,0 +1,27 @@ +# External APIs + +**Base URL:** `/api/v1/external` + +These endpoints allow external systems to push Verifiable Credential (VC) documents into running Guardian policy workflows, either by specifying a target block via URL path parameters or by resolving the policy from fields within the request body. + +**Authentication:** No authentication is required for any endpoint in this group. + +--- + +## Endpoints + +| Method | Endpoint | Description | Auth Required | +|--------|----------|-------------|---------------| +| POST | `/external/{policyId}/{blockTag}` | Send data from an external source to a specific policy block | No | +| POST | `/external` | Send data from an external source (policy resolved from request body) | No | +| POST | `/external/{policyId}/{blockTag}/sync-events` | Send data to a specific block with synchronous event response | No | +| POST | `/external/sync-events` | Send data with synchronous event response (policy resolved from request body) | No | + +--- + +## Endpoint Details + +* [Sends Data from External Source (Specific Block)](sends-data-from-external-source.md) +* [Sends Data from External Source (Generic)](sends-data-from-external-source-generic.md) +* [Sends Data with Sync Events (Specific Block)](sends-data-with-sync-events.md) +* [Sends Data with Sync Events (Generic)](sends-data-with-sync-events-generic.md) diff --git a/docs/external-apis/sends-data-from-external-source-generic.md b/docs/external-apis/sends-data-from-external-source-generic.md new file mode 100644 index 0000000000..a0d7477fe3 --- /dev/null +++ b/docs/external-apis/sends-data-from-external-source-generic.md @@ -0,0 +1,50 @@ +# Sends Data from External Source (Generic) + +**`POST /external/`** + +Sends a Verifiable Credential (VC) document from an external source. The target policy is resolved from fields within the request body. + +--- + +## Request + +### Request Body + +```json +{ + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "policyTag": "example_policy_tag", + "document": { + "@context": ["https://www.w3.org/2018/credentials/v1"], + "id": "urn:uuid:63e3e5e8-a01b-3c00-1234-abcdef012345", + "type": ["VerifiableCredential"], + "issuer": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "issuanceDate": "2024-06-01T00:00:00.000Z", + "credentialSubject": {} + } +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `owner` | string | Yes | DID of the document owner | +| `policyTag` | string | Yes | Tag of the target policy (used to resolve the destination) | +| `document` | object | Yes | The Verifiable Credential document | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/external-apis/sends-data-from-external-source.md b/docs/external-apis/sends-data-from-external-source.md index 4cb660173e..a6f83a933c 100644 --- a/docs/external-apis/sends-data-from-external-source.md +++ b/docs/external-apis/sends-data-from-external-source.md @@ -1,30 +1,57 @@ -# Sends Data from External Source +# Sends Data from External Source (Specific Block) -{% swagger method="post" path="" baseUrl="/external" summary="Sends data from an external source." %} -{% swagger-description %} -Sends data from an external source -{% endswagger-description %} +**`POST /external/{policyId}/{blockTag}`** -{% swagger-parameter in="body" name="Object" required="true" %} -Object that contains VC Document -{% endswagger-parameter %} +Sends a Verifiable Credential (VC) document from an external source to a specific policy block identified by `policyId` and `blockTag`. -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `policyId` | string | Yes | The ID of the target policy | +| `blockTag` | string | Yes | The tag name of the target policy block | + +### Request Body + +```json { - // Response + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "policyTag": "example_policy_tag", + "document": { + "@context": ["https://www.w3.org/2018/credentials/v1"], + "id": "urn:uuid:63e3e5e8-a01b-3c00-1234-abcdef012345", + "type": ["VerifiableCredential"], + "issuer": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "issuanceDate": "2024-06-01T00:00:00.000Z", + "credentialSubject": {} + } } ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `owner` | string | Yes | DID of the document owner | +| `policyTag` | string | No | Tag of the policy (used for routing when `policyId` is not in path) | +| `document` | object | Yes | The Verifiable Credential document | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/external-apis/sends-data-with-sync-events-generic.md b/docs/external-apis/sends-data-with-sync-events-generic.md new file mode 100644 index 0000000000..92b70f32e5 --- /dev/null +++ b/docs/external-apis/sends-data-with-sync-events-generic.md @@ -0,0 +1,64 @@ +# Sends Data with Sync Events (Generic) + +**`POST /external/sync-events`** + +Sends a Verifiable Credential (VC) document and returns synchronous policy events. The target policy is resolved from fields within the request body. + +--- + +## Request + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `history` | boolean | No | `false` | Whether to include historical events in the response | + +### Request Body + +```json +{ + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "policyTag": "example_policy_tag", + "document": { + "@context": ["https://www.w3.org/2018/credentials/v1"], + "id": "urn:uuid:63e3e5e8-a01b-3c00-1234-abcdef012345", + "type": ["VerifiableCredential"], + "issuer": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "issuanceDate": "2024-06-01T00:00:00.000Z", + "credentialSubject": {} + } +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `owner` | string | Yes | DID of the document owner | +| `policyTag` | string | Yes | Tag of the target policy (used to resolve the destination) | +| `document` | object | Yes | The Verifiable Credential document | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "result": true, + "events": [ + { + "blockTag": "approve_application", + "data": {} + } + ] +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/external-apis/sends-data-with-sync-events.md b/docs/external-apis/sends-data-with-sync-events.md new file mode 100644 index 0000000000..799969a721 --- /dev/null +++ b/docs/external-apis/sends-data-with-sync-events.md @@ -0,0 +1,71 @@ +# Sends Data with Sync Events (Specific Block) + +**`POST /external/{policyId}/{blockTag}/sync-events`** + +Sends a Verifiable Credential (VC) document to a specific policy block and returns synchronous policy events triggered by the submission. + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `policyId` | string | Yes | The ID of the target policy | +| `blockTag` | string | Yes | The tag name of the target policy block | + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `history` | boolean | No | `false` | Whether to include historical events in the response | + +### Request Body + +```json +{ + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "policyTag": "example_policy_tag", + "document": { + "@context": ["https://www.w3.org/2018/credentials/v1"], + "id": "urn:uuid:63e3e5e8-a01b-3c00-1234-abcdef012345", + "type": ["VerifiableCredential"], + "issuer": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "issuanceDate": "2024-06-01T00:00:00.000Z", + "credentialSubject": {} + } +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `owner` | string | Yes | DID of the document owner | +| `policyTag` | string | No | Tag of the policy | +| `document` | object | Yes | The Verifiable Credential document | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "result": true, + "events": [ + { + "blockTag": "approve_application", + "data": {} + } + ] +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/README.md b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/README.md index 27cd673b1f..0b880a06cd 100644 --- a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/README.md +++ b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/README.md @@ -2,5 +2,60 @@ icon: webhook --- -# APIs related +# APIs Related to Complex Iterative Review and Approval Workflows +These APIs enable collaborative document review within Guardian policies. Users can create discussion threads on policy documents, post messages, attach encrypted files, and inspect document relationships and schemas — all scoped to a specific policy and document. + +**Authentication:** All endpoints require a Bearer token (`Authorization: Bearer `). Obtain a token via `POST /api/v1/accounts/login`. + +--- + +## Endpoint Index + +### Policy Comments (`/api/v1/policy-comments`) + +| Method | Endpoint | Description | Auth Required | +|--------|----------|-------------|---------------| +| **`GET`** | `/policy-comments/{policyId}/{documentId}/users` | Returns users with access to the document | Yes | +| **`GET`** | `/policy-comments/{policyId}/{documentId}/relationships` | Returns documents linked to the target document | Yes | +| **`GET`** | `/policy-comments/{policyId}/{documentId}/schemas` | Returns schemas applicable to the target document | Yes | +| **`GET`** | `/policy-comments/{policyId}/{documentId}/discussions` | Returns discussion threads for the target document | Yes | +| **`POST`** | `/policy-comments/{policyId}/{documentId}/discussions` | Creates a new discussion thread | Yes | +| **`POST`** | `/policy-comments/{policyId}/{documentId}/discussions/{discussionId}/comments` | Creates a new message in a discussion | Yes | +| **`POST`** | `/policy-comments/{policyId}/{documentId}/discussions/{discussionId}/comments/search` | Returns paginated messages for a discussion | Yes | +| **`GET`** | `/policy-comments/{policyId}/{documentId}/comments/count` | Returns the total message count for a document | Yes | +| **`POST`** | `/policy-comments/{policyId}/{documentId}/discussions/{discussionId}/comments/file` | Encrypts and uploads a file to IPFS | Yes | +| **`GET`** | `/policy-comments/{policyId}/{documentId}/discussions/{discussionId}/comments/file/{cid}` | Retrieves and decrypts a file from IPFS | Yes | +| **`GET`** | `/policy-comments/{policyId}/{documentId}/keys` | Returns private keys for the target document | Yes | + +### Policy Repository (`/api/v1/policy-repository`) + +| Method | Endpoint | Description | Auth Required | +|--------|----------|-------------|---------------| +| **`GET`** | `/policy-repository/{policyId}/users` | Returns user names present in the policy | Yes | +| **`GET`** | `/policy-repository/{policyId}/schemas` | Returns schemas present in the policy | Yes | +| **`GET`** | `/policy-repository/{policyId}/documents` | Returns paginated documents in the policy | Yes | + +--- + +## Endpoints + +### Policy Comments + +- [Returns the List of Users with Access to a Document](returns-the-list-of-user-names-which-are-present-in-the-target-policy-and-have-access-to-the-target.md) +- [Returns the List of Documents Linked with the Target Document](returns-the-list-of-documents-linked-with-the-target-document.md) +- [Returns the List of Schemas for the Target Document](returns-the-list-of-schemas-for-the-target-document.md) +- [Returns the List of Discussions for the Target Document](returns-the-list-of-discussions-for-the-target-document.md) +- [Creates a New Discussion Linked to the Target Document](creates-a-new-discussion-linked-to-the-target-document.md) +- [Creates a New Message in the Target Discussion](creates-a-new-message-in-the-target-discussion.md) +- [Returns the List of Messages for the Target Discussion](returns-the-list-of-messages-for-the-target-discussion.md) +- [Returns the Count of Messages in the Target Discussion](returns-the-count-of-the-messages-in-the-target-discussion.md) +- [Encrypts and Loads the File into IPFS Linked to the Target Discussion](encrypts-and-loads-the-file-into-ipfs-linked-to-the-target-discussion.md) +- [Retrieves and Decrypts the File Associated with the Discussion from IPFS](retrieves-and-decrypts-the-file-associated-with-the-discussion-from-ipfs.md) +- [Returns the List of Private Keys for the Target Document](returns-the-list-of-private-keys-for-the-target-document.md) + +### Policy Repository + +- [Returns the List of User Names Present in the Policy](returns-the-list-of-user-names-which-are-present-in-the-policy.md) +- [Returns the List of Schemas Present in the Target Policy](returns-the-list-of-schemas-present-in-the-target-policy.md) +- [Returns the List of Documents in the Target Policy](returns-the-list-of-documents-in-the-target-policy.md) diff --git a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/creates-a-new-discussion-linked-to-the-target-document.md b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/creates-a-new-discussion-linked-to-the-target-document.md index 9a59af2920..004206e193 100644 --- a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/creates-a-new-discussion-linked-to-the-target-document.md +++ b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/creates-a-new-discussion-linked-to-the-target-document.md @@ -1,59 +1,61 @@ -# Creates a new discussion linked to the target document +# Creates a New Discussion Linked to the Target Document -`POST` `/policy-comments/{policyId}/{documentId}/schemas` +**`POST /api/v1/policy-comments/{policyId}/{documentId}/discussions`** -Creates a new discussion linked to the target document +Creates a new discussion thread linked to the target document. -**Headers** +**Authentication:** Bearer token required (`Authorization: Bearer `) -| Name | Value | -| ------------- | ------------------ | -| Content-Type | `application/json` | -| Authorization | `Bearer ` | +**Permission:** `Permissions.POLICIES_POLICY_EXECUTE` or `Permissions.POLICIES_POLICY_MANAGE` -**Body** +--- -| Name | Type | Description | -| ---------- | ------ | ------------------- | -| policyId | string | Policy ID | -| documentId | string | Document Identifier | +## Request -**Response** +### Path Parameters -{% tabs %} -{% tab title="200" %} -```json5 -description: Successful operation. - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/PolicyDiscussionDTO' -``` -{% endtab %} +| Parameter | Type | Required | Description | +|--------------|--------|----------|---------------------| +| `policyId` | string | Yes | Policy identifier | +| `documentId` | string | Yes | Document identifier | + +### Request Body -{% tab title="401" %} -```json5 +```json { - description: Unauthorized. + "title": "Query about facility capacity value", + "message": "The reported capacity of 500 MWh seems high — please verify." } ``` -{% endtab %} -{% tab title="403" %} -```json5 -description: Forbidden. -``` -{% endtab %} - -{% tab title="500" %} -```json5 -description: Internal server error. - content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +| Field | Type | Required | Description | +|-----------|--------|----------|------------------------------| +| `title` | string | Yes | Discussion title or subject | +| `message` | string | No | Optional initial message body | + +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "title": "Query about facility capacity value", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "createDate": "2026-03-30T10:00:00.000Z", + "commentCount": 0 +} ``` -{% endtab %} -{% endtabs %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Validation error — invalid field values | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/creates-a-new-message-in-the-target-discussion.md b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/creates-a-new-message-in-the-target-discussion.md index e8de4393c2..e8eeb093a5 100644 --- a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/creates-a-new-message-in-the-target-discussion.md +++ b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/creates-a-new-message-in-the-target-discussion.md @@ -1,58 +1,64 @@ -# Creates a new message in the target discussion +# Creates a New Message in the Target Discussion -`POST` `/policy-comments/{policyId}/{documentId}/discussions/{discussionId}/comments` +**`POST /api/v1/policy-comments/{policyId}/{documentId}/discussions/{discussionId}/comments`** -Creates a new message in the target discussion +Creates a new message in the target discussion thread. -**Headers** +**Authentication:** Bearer token required (`Authorization: Bearer `) -| Name | Value | -| ------------- | ------------------ | -| Content-Type | `application/json` | -| Authorization | `Bearer ` | +**Permission:** `Permissions.POLICIES_POLICY_EXECUTE` or `Permissions.POLICIES_POLICY_MANAGE` -**Body** +--- -| Name | Type | Description | -| ------------ | ------ | --------------------- | -| policyId | string | Policy ID | -| documentId | string | Document Identifier | -| discussionId | string | Discussion Identifier | +## Request -**Response** +### Path Parameters -{% tabs %} -{% tab title="200" %} -```json5 -description: Successful operation. - content: - application/json: - schema: - $ref: '#/components/schemas/PolicyCommentDTO' -``` -{% endtab %} +| Parameter | Type | Required | Description | +|----------------|--------|----------|-------------------------| +| `policyId` | string | Yes | Policy identifier | +| `documentId` | string | Yes | Document identifier | +| `discussionId` | string | Yes | Discussion identifier | + +### Request Body -{% tab title="401" %} -```json5 +```json { - description: Unauthorized. + "message": "The capacity figure should be 50 MWh — the extra zero appears to be a typo.", + "mentionedUsers": [ + "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001" + ] } ``` -{% endtab %} -{% tab title="403" %} -```json5 -description: Forbidden. -``` -{% endtab %} - -{% tab title="500" %} -```json5 -description: Internal server error. - content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +| Field | Type | Required | Description | +|------------------|----------|----------|---------------------------------------| +| `message` | string | Yes | Comment text content | +| `mentionedUsers` | string[] | No | Array of user DIDs to mention/notify | + +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "message": "The capacity figure should be 50 MWh — the extra zero appears to be a typo.", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "createDate": "2026-03-30T10:05:00.000Z" +} ``` -{% endtab %} -{% endtabs %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Validation error — invalid field values | +| `500 Internal Server Error` | Unexpected server failure | +| `503 Service Unavailable` | Policy block unavailable | diff --git a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/encrypts-and-loads-the-file-into-ipfs-linked-to-the-target-discussion.md b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/encrypts-and-loads-the-file-into-ipfs-linked-to-the-target-discussion.md index 5b64192bb8..5b6e838493 100644 --- a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/encrypts-and-loads-the-file-into-ipfs-linked-to-the-target-discussion.md +++ b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/encrypts-and-loads-the-file-into-ipfs-linked-to-the-target-discussion.md @@ -1,58 +1,55 @@ -# Encrypts and loads the file into IPFS linked to the target discussion +# Encrypts and Loads the File into IPFS Linked to the Target Discussion -`POST` `/policy-comments/{policyId}/{documentId}/discussions/{discussionId}/comments/file` +**`POST /api/v1/policy-comments/{policyId}/{documentId}/discussions/{discussionId}/comments/file`** -Encrypts and loads the file into IPFS linked to the target discussion +Encrypts and uploads a file to IPFS, attaching it to the target discussion thread. -**Headers** +**Authentication:** Bearer token required (`Authorization: Bearer `) -| Name | Value | -| ------------- | ------------------ | -| Content-Type | `application/json` | -| Authorization | `Bearer ` | +**Permission:** `Permissions.POLICIES_POLICY_EXECUTE` or `Permissions.POLICIES_POLICY_MANAGE` -**Body** +--- -| Name | Type | Description | -| ------------ | ------ | --------------------- | -| policyId | string | Policy ID | -| documentId | string | Document Identifier | -| discussionId | string | Discussion Identifier | +## Request -**Response** +### Path Parameters -{% tabs %} -{% tab title="200" %} -```json5 -description: Successful operation. - content: - application/json: - schema: - type: string -``` -{% endtab %} +| Parameter | Type | Required | Description | +|----------------|--------|----------|-----------------------| +| `policyId` | string | Yes | Policy identifier | +| `documentId` | string | Yes | Document identifier | +| `discussionId` | string | Yes | Discussion identifier | + +### Request Body + +Binary file data. The request body must not be empty. -{% tab title="401" %} -```json5 -{ - description: Unauthorized. -} ``` -{% endtab %} +Content-Type: application/octet-stream -{% tab title="403" %} -```json5 -description: Forbidden. + ``` -{% endtab %} - -{% tab title="500" %} -```json5 -description: Internal server error. - content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' + +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +Returns the IPFS CID of the uploaded file as a JSON string. + +```json +"bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi" ``` -{% endtab %} -{% endtabs %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `400 Bad Request` | File could not be uploaded to IPFS | +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Request body is empty | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/retrieves-and-decrypts-the-file-associated-with-the-discussion-from-ipfs.md b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/retrieves-and-decrypts-the-file-associated-with-the-discussion-from-ipfs.md index e1f1bd26e6..dfd121206a 100644 --- a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/retrieves-and-decrypts-the-file-associated-with-the-discussion-from-ipfs.md +++ b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/retrieves-and-decrypts-the-file-associated-with-the-discussion-from-ipfs.md @@ -1,60 +1,47 @@ -# Retrieves and decrypts the file associated with the discussion from IPFS +# Retrieves and Decrypts the File Associated with the Discussion from IPFS -`GET` `/policy-comments/{policyId}/{documentId}/discussions/{discussionId}/comments/file/{cid}` +**`GET /api/v1/policy-comments/{policyId}/{documentId}/discussions/{discussionId}/comments/file/{cid}`** -Retrieves and decrypts the file associated with the discussion from IPFS +Retrieves and decrypts the file associated with the discussion from IPFS. -**Headers** +**Authentication:** Bearer token required (`Authorization: Bearer `) -| Name | Value | -| ------------- | ------------------ | -| Content-Type | `application/json` | -| Authorization | `Bearer ` | +**Permission:** `Permissions.POLICIES_POLICY_EXECUTE`, `Permissions.POLICIES_POLICY_MANAGE`, or `Permissions.POLICIES_POLICY_AUDIT` -**Body** +--- -| Name | Type | Description | -| ------------ | ------ | --------------------- | -| policyId | string | Policy ID | -| documentId | string | Document Identifier | -| discussionId | string | Discussion Identifier | -| cid | string | File cid | +## Request -**Response** +### Path Parameters -{% tabs %} -{% tab title="200" %} -```json5 -description: Successful operation. - content: - application/json: - schema: - type: string - format: binary -``` -{% endtab %} +| Parameter | Type | Required | Description | +|----------------|--------|----------|---------------------------------| +| `policyId` | string | Yes | Policy identifier | +| `documentId` | string | Yes | Document identifier | +| `discussionId` | string | Yes | Discussion identifier | +| `cid` | string | Yes | IPFS CID of the encrypted file | -{% tab title="401" %} -```json5 -{ - description: Unauthorized. -} -``` -{% endtab %} +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +Returns the decrypted file as a binary stream. -{% tab title="403" %} -```json5 -description: Forbidden. ``` -{% endtab %} - -{% tab title="500" %} -```json5 -description: Internal server error. - content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +Content-Type: application/octet-stream + + ``` -{% endtab %} -{% endtabs %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | File not found in IPFS for the given CID | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-count-of-the-messages-in-the-target-discussion.md b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-count-of-the-messages-in-the-target-discussion.md index 7ab19db956..7896ea06da 100644 --- a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-count-of-the-messages-in-the-target-discussion.md +++ b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-count-of-the-messages-in-the-target-discussion.md @@ -1,67 +1,44 @@ -# Returns the count of the messages in the target discussion +# Returns the Count of Messages in the Target Discussion -`GET` `/policy-comments/{policyId}/{documentId}/comments/count` +**`GET /api/v1/policy-comments/{policyId}/{documentId}/comments/count`** -Returns the count of the messages in the target discussion +Returns the total count of messages across all discussions for the target document. -**Headers** +**Authentication:** Bearer token required (`Authorization: Bearer `) -| Name | Value | -| ------------- | ------------------ | -| Content-Type | `application/json` | -| Authorization | `Bearer ` | +**Permission:** `Permissions.POLICIES_POLICY_EXECUTE` or `Permissions.POLICIES_POLICY_MANAGE` -**Body** +--- -| Name | Type | Description | -| ---------- | ------ | ------------------- | -| policyId | string | Policy ID | -| documentId | string | Document Identifier | +## Request -**Response** +### Path Parameters -{% tabs %} -{% tab title="200" %} -```json5 -description: Successful operation. - content: - application/json: - schema: - $ref: '#/components/schemas/PolicyCommentDTO' -``` -{% endtab %} +| Parameter | Type | Required | Description | +|--------------|--------|----------|---------------------| +| `policyId` | string | Yes | Policy identifier | +| `documentId` | string | Yes | Document identifier | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` -{% tab title="401" %} -```json5 +```json { - description: Unauthorized. + "count": 12 } ``` -{% endtab %} -{% tab title="403" %} -```json5 -description: Forbidden. -``` -{% endtab %} - -{% tab title="500" %} -```json5 -description: Internal server error. - content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' -``` -{% endtab %} +### Error Responses -{% tab title="503" %} -```json5 -description: Block Unavailable. - content: - application/json: - schema: - $ref: '#/components/schemas/ServiceUnavailableErrorDTO' -``` -{% endtab %} -{% endtabs %} +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Validation error — invalid field values | +| `500 Internal Server Error` | Unexpected server failure | +| `503 Service Unavailable` | Policy block unavailable | diff --git a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-discussions-for-the-target-document.md b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-discussions-for-the-target-document.md index 563c99171a..63e8f4da68 100644 --- a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-discussions-for-the-target-document.md +++ b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-discussions-for-the-target-document.md @@ -1,62 +1,57 @@ -# Returns the list of discussions for the target document +# Returns the List of Discussions for the Target Document -`GET` `/policy-comments/{policyId}/{documentId}/discussions` +**`GET /api/v1/policy-comments/{policyId}/{documentId}/discussions`** -Returns the list of discussions for the target document +Returns the list of discussion threads for the target document. -**Headers** +**Authentication:** Bearer token required (`Authorization: Bearer `) -| Name | Value | -| ------------- | ------------------ | -| Content-Type | `application/json` | -| Authorization | `Bearer ` | +**Permission:** `Permissions.POLICIES_POLICY_EXECUTE`, `Permissions.POLICIES_POLICY_MANAGE`, or `Permissions.POLICIES_POLICY_AUDIT` -**Body** +--- -| Name | Type | Description | -| ---------- | ------- | ------------------- | -| policyId | string | Policy ID | -| documentId | string | Document Identifier | -| search | string | Search | -| field | string | Field path | -| readonly | boolean | Read only | +## Request -**Response** +### Path Parameters -{% tabs %} -{% tab title="200" %} -```json5 -description: Successful operation. - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/PolicyDiscussionDTO' -``` -{% endtab %} +| Parameter | Type | Required | Description | +|--------------|--------|----------|---------------------| +| `policyId` | string | Yes | Policy identifier | +| `documentId` | string | Yes | Document identifier | -{% tab title="401" %} -```json5 -{ - description: Unauthorized. -} -``` -{% endtab %} +### Query Parameters -{% tab title="403" %} -```json5 -description: Forbidden. -``` -{% endtab %} - -{% tab title="500" %} -```json5 -description: Internal server error. - content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +| Parameter | Type | Required | Default | Description | +|------------|---------|----------|---------|------------------------------------------------------------------| +| `search` | string | No | — | Filter discussions by text search | +| `field` | string | No | — | Filter discussions by field path | +| `readonly` | boolean | No | false | When `true` and the caller has audit permission, enables audit mode | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "title": "Please review facility capacity value", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "createDate": "2026-03-30T10:00:00.000Z", + "commentCount": 3 + } +] ``` -{% endtab %} -{% endtabs %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Invalid `policyId` value | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-documents-in-the-target-policy.md b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-documents-in-the-target-policy.md index 8616d0c3cf..f3fdffadea 100644 --- a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-documents-in-the-target-policy.md +++ b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-documents-in-the-target-policy.md @@ -1,69 +1,61 @@ -# Returns the list of documents in the target policy - -`GET` `/policy-repository/{policyId}/documents` - -Returns the list of documents in the target policy - -**Headers** - -| Name | Value | -| ------------- | ------------------ | -| Content-Type | `application/json` | -| Authorization | `Bearer ` | - -**Body** - -| Name | Type | Description | -| --------- | ------- | ---------------------------------------------------------------------- | -| policyId | string | Policy ID | -| pageIndex | number | The number of pages to skip before starting to collect the result set. | -| pageSize | number | The number of items to return | -| type | string | Type of Document | -| owner | string | Document Owner | -| schema | string | Document Schema | -| comments | boolean | Load Comments | - -**Response** - -{% tabs %} -{% tab title="200" %} -```json5 -description: Successful operation. - headers: - X-Total-Count: - schema: - type: integer - description: Total items in the collection. - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/VcDocumentDTO' -``` -{% endtab %} +# Returns the List of Documents in the Target Policy -{% tab title="401" %} -```json5 -{ - description: Unauthorized. -} -``` -{% endtab %} +**`GET /api/v1/policy-repository/{policyId}/documents`** -{% tab title="403" %} -```json5 -description: Forbidden. -``` -{% endtab %} - -{% tab title="500" %} -```json5 -description: Internal server error. - content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +Returns the paginated list of documents in the target policy. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.POLICIES_POLICY_AUDIT` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|------------|--------|----------|-------------------| +| `policyId` | string | Yes | Policy identifier | + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-------------|---------|----------|---------|-------------------------------------------------------------------| +| `pageIndex` | number | No | 0 | Zero-based page index | +| `pageSize` | number | No | 20 | Number of items to return per page | +| `type` | string | No | — | Filter by document type (e.g. `VC`) | +| `owner` | string | No | — | Filter by document owner DID | +| `schema` | string | No | — | Filter by document schema UUID | +| `comments` | boolean | No | — | When `true`, includes associated discussion comments in the response | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +The response includes an `X-Total-Count` header with the total number of matching documents. + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "type": "VC", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "schema": "#facility-schema", + "createDate": "2026-03-30T10:00:00.000Z" + } +] ``` -{% endtab %} -{% endtabs %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Invalid `policyId` value | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-documents-linked-with-the-target-document.md b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-documents-linked-with-the-target-document.md index 901ec73e74..2aa3e94bcd 100644 --- a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-documents-linked-with-the-target-document.md +++ b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-documents-linked-with-the-target-document.md @@ -1,61 +1,48 @@ -# Returns the list of documents linked with the target document +# Returns the List of Documents Linked with the Target Document -`GET` `/policy-comments/{policyId}/{documentId}/relationships` +**`GET /api/v1/policy-comments/{policyId}/{documentId}/relationships`** Returns the list of documents linked with the target document. -**Headers** - -| Name | Value | -| ------------- | ------------------ | -| Content-Type | `application/json` | -| Authorization | `Bearer ` | - -**Body** - -| Name | Type | Description | -| ---------- | ------ | ------------------- | -| policyId | string | Policy ID | -| documentId | string | Document Identifier | - -**Response** - -{% tabs %} -{% tab title="200" %} -```json5 -{ - description: Successful operation. - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/PolicyCommentUserDTO' -} -``` -{% endtab %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% tab title="401" %} -```json5 -{ - description: Unauthorized. -} -``` -{% endtab %} +**Permission:** `Permissions.POLICIES_POLICY_EXECUTE`, `Permissions.POLICIES_POLICY_MANAGE`, or `Permissions.POLICIES_POLICY_AUDIT` -{% tab title="403" %} -```json5 -description: Forbidden. -``` -{% endtab %} - -{% tab title="500" %} -```json5 -description: Internal server error. - content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|--------------|--------|----------|---------------------| +| `policyId` | string | Yes | Policy identifier | +| `documentId` | string | Yes | Document identifier | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "type": "VC", + "relationship": "parent", + "schema": "#facility-schema" + } +] ``` -{% endtab %} -{% endtabs %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Invalid `policyId` value | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-messages-for-the-target-discussion.md b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-messages-for-the-target-discussion.md index 977aa3abe0..7fa9d80fc5 100644 --- a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-messages-for-the-target-discussion.md +++ b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-messages-for-the-target-discussion.md @@ -1,66 +1,73 @@ -# Returns the list of messages for the target discussion - -`POST` `/policy-comments/{policyId}/{documentId}/discussions/{discussionId}/comments/search` - -Returns the list of messages for the target discussion - -**Headers** - -| Name | Value | -| ------------- | ------------------ | -| Content-Type | `application/json` | -| Authorization | `Bearer ` | - -**Body** - -| Name | Type | Description | -| ------------ | ------- | --------------------- | -| policyId | string | Policy ID | -| documentId | string | Document Identifier | -| discussionId | string | Discussion Identifier | -| readonly | boolean | ReadOnly | - -**Response** - -{% tabs %} -{% tab title="200" %} -```json5 -description: Successful operation. - headers: - X-Total-Count: - schema: - type: integer - description: Total items in the collection. - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/PolicyCommentDTO' -``` -{% endtab %} +# Returns the List of Messages for the Target Discussion + +**`POST /api/v1/policy-comments/{policyId}/{documentId}/discussions/{discussionId}/comments/search`** + +Returns the paginated list of messages for the target discussion. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.POLICIES_POLICY_EXECUTE`, `Permissions.POLICIES_POLICY_MANAGE`, or `Permissions.POLICIES_POLICY_AUDIT` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|----------------|--------|----------|-----------------------| +| `policyId` | string | Yes | Policy identifier | +| `documentId` | string | Yes | Document identifier | +| `discussionId` | string | Yes | Discussion identifier | + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|------------|---------|----------|---------|----------------------------------------------------------------------| +| `readonly` | boolean | No | false | When `true` and the caller has audit permission, enables audit mode | -{% tab title="401" %} -```json5 +### Request Body + +```json { - description: Unauthorized. + "pageIndex": 0, + "pageSize": 25, + "from": "2026-01-01T00:00:00.000Z" } ``` -{% endtab %} -{% tab title="403" %} -```json5 -description: Forbidden. -``` -{% endtab %} - -{% tab title="500" %} -```json5 -description: Internal server error. - content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +| Field | Type | Required | Description | +|-------------|--------|----------|-----------------------------------------------| +| `pageIndex` | number | No | Zero-based page index | +| `pageSize` | number | No | Number of items per page | +| `from` | string | No | Filter comments created after this timestamp (ISO 8601) | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +The response includes an `X-Total-Count` header with the total number of messages. + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "message": "The capacity figure should be 50 MWh — the extra zero appears to be a typo.", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "createDate": "2026-03-30T10:05:00.000Z", + "files": [] + } +] ``` -{% endtab %} -{% endtabs %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-private-keys-for-the-target-document.md b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-private-keys-for-the-target-document.md index 02fc6290fe..03ffb58f80 100644 --- a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-private-keys-for-the-target-document.md +++ b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-private-keys-for-the-target-document.md @@ -1,59 +1,51 @@ -# Returns the list of private keys for the target document +# Returns the List of Private Keys for the Target Document -`GET` `/policy-comments/{policyId}/{documentId}/keys` +**`GET /api/v1/policy-comments/{policyId}/{documentId}/keys`** -Returns the list of private keys for the target document +Returns the list of private keys for the target document, used to decrypt discussion content. -**Headers** +**Authentication:** Bearer token required (`Authorization: Bearer `) -| Name | Value | -| ------------- | ------------------ | -| Content-Type | `application/json` | -| Authorization | `Bearer ` | +**Permission:** `Permissions.POLICIES_POLICY_AUDIT` -**Body** +--- -| Name | Type | Description | -| ------------ | ------ | --------------------- | -| policyId | string | Policy ID | -| documentId | string | Document Identifier | -| discussionId | string | Discussion Identifier | +## Request -**Response** +### Path Parameters -{% tabs %} -{% tab title="200" %} -```json5 -description: Successful operation. - content: - application/json: - schema: - type: string - format: binary -``` -{% endtab %} +| Parameter | Type | Required | Description | +|--------------|--------|----------|---------------------| +| `policyId` | string | Yes | Policy identifier | +| `documentId` | string | Yes | Document identifier | -{% tab title="401" %} -```json5 -{ - description: Unauthorized. -} -``` -{% endtab %} +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|----------------|--------|----------|---------|----------------------------------------------------| +| `discussionId` | string | No | — | Filter keys for a specific discussion identifier | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +Returns the private key material as a binary stream. -{% tab title="403" %} -```json5 -description: Forbidden. ``` -{% endtab %} - -{% tab title="500" %} -```json5 -description: Internal server error. - content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +Content-Type: application/octet-stream + + ``` -{% endtab %} -{% endtabs %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Key not found for the given document | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-schemas-for-the-target-document.md b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-schemas-for-the-target-document.md index 60e780341b..40b48cb260 100644 --- a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-schemas-for-the-target-document.md +++ b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-schemas-for-the-target-document.md @@ -1,61 +1,48 @@ -# Returns the list of schemas for the target document +# Returns the List of Schemas for the Target Document -`GET` `/policy-comments/{policyId}/{documentId}/schemas` +**`GET /api/v1/policy-comments/{policyId}/{documentId}/schemas`** -Returns the list of schemas for the target document +Returns the list of schemas applicable to the target document within the policy. -**Headers** +**Authentication:** Bearer token required (`Authorization: Bearer `) -| Name | Value | -| ------------- | ------------------ | -| Content-Type | `application/json` | -| Authorization | `Bearer ` | +**Permission:** `Permissions.POLICIES_POLICY_EXECUTE`, `Permissions.POLICIES_POLICY_MANAGE`, or `Permissions.POLICIES_POLICY_AUDIT` -**Body** +--- -| Name | Type | Description | -| ---------- | ------ | ------------------- | -| policyId | string | Policy ID | -| documentId | string | Document Identifier | +## Request -**Response** +### Path Parameters -{% tabs %} -{% tab title="200" %} -```json5 -{ - description: Successful operation. - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/PolicyCommentUserDTO' -} -``` -{% endtab %} +| Parameter | Type | Required | Description | +|--------------|--------|----------|---------------------| +| `policyId` | string | Yes | Policy identifier | +| `documentId` | string | Yes | Document identifier | -{% tab title="401" %} -```json5 -{ - description: Unauthorized. -} -``` -{% endtab %} +--- -{% tab title="403" %} -```json5 -description: Forbidden. -``` -{% endtab %} - -{% tab title="500" %} -```json5 -description: Internal server error. - content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +## Response + +### Success Response + +**Status:** `200 OK` + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "name": "Facility Schema", + "version": "1.0.0", + "iri": "#facility-schema" + } +] ``` -{% endtab %} -{% endtabs %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Invalid `policyId` value | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-schemas-present-in-the-target-policy.md b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-schemas-present-in-the-target-policy.md index 7eb2d6e547..fccff0d877 100644 --- a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-schemas-present-in-the-target-policy.md +++ b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-schemas-present-in-the-target-policy.md @@ -1,58 +1,47 @@ -# Returns the list of schemas present in the target policy +# Returns the List of Schemas Present in the Target Policy -`GET` `/policy-repository/{policyId}/schemas` +**`GET /api/v1/policy-repository/{policyId}/schemas`** -Returns the list of schemas present in the target policy +Returns the list of schemas present in the target policy. -**Headers** +**Authentication:** Bearer token required (`Authorization: Bearer `) -| Name | Value | -| ------------- | ------------------ | -| Content-Type | `application/json` | -| Authorization | `Bearer ` | +**Permission:** `Permissions.POLICIES_POLICY_AUDIT` -**Body** +--- -| Name | Type | Description | -| -------- | ------ | ----------- | -| policyId | string | Policy ID | +## Request -**Response** +### Path Parameters -{% tabs %} -{% tab title="200" %} -```json5 -description: Successful operation. - content: - application/json: - schema: - type: array - items: - type: object -``` -{% endtab %} +| Parameter | Type | Required | Description | +|------------|--------|----------|-------------------| +| `policyId` | string | Yes | Policy identifier | -{% tab title="401" %} -```json5 -{ - description: Unauthorized. -} -``` -{% endtab %} +--- -{% tab title="403" %} -```json5 -description: Forbidden. -``` -{% endtab %} - -{% tab title="500" %} -```json5 -description: Internal server error. - content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +## Response + +### Success Response + +**Status:** `200 OK` + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "name": "Facility Schema", + "version": "1.0.0", + "iri": "#facility-schema" + } +] ``` -{% endtab %} -{% endtabs %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Invalid `policyId` value | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-user-names-which-are-present-in-the-policy.md b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-user-names-which-are-present-in-the-policy.md index 9593e1c903..2dc8811fd0 100644 --- a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-user-names-which-are-present-in-the-policy.md +++ b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-user-names-which-are-present-in-the-policy.md @@ -1,58 +1,46 @@ -# Returns the list of user names which are present in the policy +# Returns the List of User Names Present in the Policy -`GET` `/policy-repository/{policyId}/users` +**`GET /api/v1/policy-repository/{policyId}/users`** -Returns the list of user names which are present in the policy +Returns the list of user names which are present in the target policy. -**Headers** +**Authentication:** Bearer token required (`Authorization: Bearer `) -| Name | Value | -| ------------- | ------------------ | -| Content-Type | `application/json` | -| Authorization | `Bearer ` | +**Permission:** `Permissions.POLICIES_POLICY_AUDIT` -**Body** +--- -| Name | Type | Description | -| -------- | ------ | ----------- | -| policyId | string | Policy ID | +## Request -**Response** +### Path Parameters -{% tabs %} -{% tab title="200" %} -```json5 -description: Successful operation. - content: - application/json: - schema: - type: array - items: - type: object -``` -{% endtab %} +| Parameter | Type | Required | Description | +|------------|--------|----------|-------------------| +| `policyId` | string | Yes | Policy identifier | -{% tab title="401" %} -```json5 -{ - description: Unauthorized. -} -``` -{% endtab %} +--- -{% tab title="403" %} -```json5 -description: Forbidden. -``` -{% endtab %} - -{% tab title="500" %} -```json5 -description: Internal server error. - content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +## Response + +### Success Response + +**Status:** `200 OK` + +```json +[ + { + "username": "example_user", + "did": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "role": "OWNER" + } +] ``` -{% endtab %} -{% endtabs %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Invalid `policyId` value | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-user-names-which-are-present-in-the-target-policy-and-have-access-to-the-target.md b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-user-names-which-are-present-in-the-target-policy-and-have-access-to-the-target.md index 27ac553944..b41527bf4b 100644 --- a/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-user-names-which-are-present-in-the-target-policy-and-have-access-to-the-target.md +++ b/docs/guardian/complex-iterative-review-and-approval-workflows/apis-related/returns-the-list-of-user-names-which-are-present-in-the-target-policy-and-have-access-to-the-target.md @@ -1,62 +1,47 @@ -# Returns the list of user names which are present in the target policy and have access to the target +# Returns the List of Users with Access to a Document -`GET` `/policy-comments/{policyId}/{documentId}/users` +**`GET /api/v1/policy-comments/{policyId}/{documentId}/users`** -Returns the list of user names which are present in the target policy\ -and have access to the target document. +Returns the list of user names which are present in the target policy and have access to the target document. -**Headers** +**Authentication:** Bearer token required (`Authorization: Bearer `) -| Name | Value | -| ------------- | ------------------ | -| Content-Type | `application/json` | -| Authorization | `Bearer ` | +**Permission:** `Permissions.POLICIES_POLICY_EXECUTE`, `Permissions.POLICIES_POLICY_MANAGE`, or `Permissions.POLICIES_POLICY_AUDIT` -**Body** +--- -| Name | Type | Description | -| ---------- | ------ | ------------------- | -| policyId | string | Policy ID | -| documentId | string | Document Identifier | +## Request -**Response** +### Path Parameters -{% tabs %} -{% tab title="200" %} -```json5 -{ - description: Successful operation. - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/PolicyCommentUserDTO' -} -``` -{% endtab %} +| Parameter | Type | Required | Description | +|--------------|--------|----------|----------------------| +| `policyId` | string | Yes | Policy identifier | +| `documentId` | string | Yes | Document identifier | -{% tab title="401" %} -```json5 -{ - description: Unauthorized. -} -``` -{% endtab %} +--- -{% tab title="403" %} -```json5 -description: Forbidden. -``` -{% endtab %} - -{% tab title="500" %} -```json5 -description: Internal server error. - content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +## Response + +### Success Response + +**Status:** `200 OK` + +```json +[ + { + "username": "example_user", + "did": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "role": "OWNER" + } +] ``` -{% endtab %} -{% endtabs %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Invalid `policyId` value | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/global-indexer/indexer-apis/README.md b/docs/guardian/global-indexer/indexer-apis/README.md index a7a5e8d33d..a1d6e39378 100644 --- a/docs/guardian/global-indexer/indexer-apis/README.md +++ b/docs/guardian/global-indexer/indexer-apis/README.md @@ -1,2 +1,120 @@ -# Indexer APIs +# Global Indexer APIs +Endpoints for the Guardian Global Indexer service, which provides search and analytics across all Hedera-based Guardian entities including policies, schemas, tokens, DIDs, VCs, VPs, and more. + +**Authentication:** Bearer token required for most endpoints (`Authorization: Bearer `) + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `GET` | `/api/v1/search` | Full-text search across all indexed entities | Yes | +| `GET` | `/api/v1/entities/did-documents` | Returns all indexed DID documents | Yes | +| `GET` | `/api/v1/entities/did-documents/{messageId}` | Returns a DID document by message ID | Yes | +| `GET` | `/api/v1/entities/did-documents/{messageId}/relationships` | Returns DID relationships | Yes | +| `GET` | `/api/v1/entities/vc-documents` | Returns all indexed VC documents | Yes | +| `GET` | `/api/v1/entities/vc-documents/{messageId}` | Returns a VC document by message ID | Yes | +| `GET` | `/api/v1/entities/vc-documents/{messageId}/relationships` | Returns VC document relationships | Yes | +| `GET` | `/api/v1/entities/vp-documents` | Returns all indexed VP documents | Yes | +| `GET` | `/api/v1/entities/vp-documents/{messageId}` | Returns a VP document by message ID | Yes | +| `GET` | `/api/v1/entities/vp-documents/{messageId}/relationships` | Returns VP document relationships | Yes | +| `GET` | `/api/v1/entities/policies` | Returns all indexed policies | Yes | +| `GET` | `/api/v1/entities/policies/{messageId}` | Returns a policy by message ID | Yes | +| `GET` | `/api/v1/entities/policies/{messageId}/relationships` | Returns policy relationships | Yes | +| `GET` | `/api/v1/entities/schemas` | Returns all indexed schemas | Yes | +| `GET` | `/api/v1/entities/schemas/{messageId}` | Returns a schema by message ID | Yes | +| `GET` | `/api/v1/entities/schemas/{messageId}/tree` | Returns the schema tree | Yes | +| `GET` | `/api/v1/entities/tokens` | Returns all indexed tokens | Yes | +| `GET` | `/api/v1/entities/tokens/{tokenId}` | Returns a token by token ID | Yes | +| `GET` | `/api/v1/entities/nfts` | Returns all indexed NFTs | Yes | +| `GET` | `/api/v1/entities/nfts/{serialNumber}` | Returns an NFT by serial number | Yes | +| `GET` | `/api/v1/entities/topics` | Returns all indexed Hedera topics | Yes | +| `GET` | `/api/v1/entities/topics/{topicId}` | Returns a topic by topic ID | Yes | +| `GET` | `/api/v1/entities/contracts` | Returns all indexed retirement contracts | Yes | +| `GET` | `/api/v1/entities/contracts/{messageId}` | Returns a contract by message ID | Yes | +| `GET` | `/api/v1/entities/modules` | Returns all indexed modules | Yes | +| `GET` | `/api/v1/entities/modules/{messageId}` | Returns a module by message ID | Yes | +| `GET` | `/api/v1/entities/tools` | Returns all indexed tools | Yes | +| `GET` | `/api/v1/entities/tools/{messageId}` | Returns a tool by message ID | Yes | +| `GET` | `/api/v1/entities/roles` | Returns all indexed roles | Yes | +| `GET` | `/api/v1/entities/roles/{messageId}` | Returns a role by message ID | Yes | +| `GET` | `/api/v1/entities/standard-registries` | Returns all indexed Standard Registry accounts | Yes | +| `GET` | `/api/v1/entities/standard-registries/{messageId}` | Returns a Standard Registry by message ID | Yes | +| `GET` | `/api/v1/entities/standard-registries/{messageId}/relationships` | Returns Standard Registry relationships | Yes | +| `GET` | `/api/v1/entities/registry-users` | Returns all indexed registry users | Yes | +| `GET` | `/api/v1/entities/registry-users/{messageId}` | Returns a registry user by message ID | Yes | +| `GET` | `/api/v1/entities/formulas` | Returns all indexed formulas | Yes | +| `GET` | `/api/v1/entities/formulas/{messageId}` | Returns a formula by message ID | Yes | +| `GET` | `/api/v1/entities/formulas/{messageId}/relationships` | Returns formula relationships | Yes | +| `GET` | `/api/v1/analytics/search/policies` | Returns search results for policies | Yes | +| `GET` | `/api/v1/analytics/compare/policy/original/{messageId}` | Compares policy changes by message ID | Yes | +| `GET` | `/api/v1/analytics/derivations/{messageId}` | Returns policy derivations | Yes | +| `GET` | `/api/v1/landing` | Returns landing page analytics | No | +| `GET` | `/api/v1/landing/settings` | Returns Hedera network explorer settings | No | +| `GET` | `/api/v1/landing/network` | Returns the Hedera network name | No | +| `GET` | `/api/v1/landing/coordinates` | Returns project geo-coordinates | No | +| `POST` | `/api/v1/landing/data-priority-policy` | Adds policy data to the priority loading queue | Yes | +| `POST` | `/api/v1/landing/data-priority-tokens` | Adds token data to the priority loading queue | Yes | +| `POST` | `/api/v1/landing/data-priority-topics` | Adds topic data to the priority loading queue | Yes | +| `POST` | `/api/v1/landing/data-priority-any/{entityId}` | Adds any entity to the priority loading queue | Yes | +| `GET` | `/api/v1/landing/progress` | Returns data loading progress | Yes | +| `POST` | `/api/v1/entities/update-files` | Refreshes linked files for the selected documents | Yes | +| `GET` | `/api/v1/artifacts/files/{fileId}` | Downloads a file by ID | Yes | +| `DELETE` | `/api/v1/ipfs/file/{cid}` | Removes a file from IPFS by CID | Yes | + +## Endpoints + +- [Full-Text Indexer Search](full-text-indexer-search.md) +- [Returns DIDs](returns-dids.md) +- [Returns DID as per Message ID](returns-did-as-per-messageid.md) +- [Returns DID Relationships](returns-did-relationships.md) +- [Returns VC Documents](returns-vc-documents.md) +- [Returns VC Document as per Message ID](returns-vc-document-as-per-messageid.md) +- [Returns VC Relationships](returns-vc-relationships.md) +- [Returns VP Documents](returns-vp-documents.md) +- [Returns VP Document as per Message ID](returns-vp-document-as-per-messageid.md) +- [Returns VP Relationships](returns-vp-relationships.md) +- [Returns Policies](returns-policies.md) +- [Returns Policy as per Message ID](returns-policy-as-per-messageid.md) +- [Returns Policy Relationships](returns-policy-relationships.md) +- [Returns Schemas](returns-schemas.md) +- [Returns Schema as per Message ID](returns-schema-as-per-messageid.md) +- [Returns Schema Tree](returns-schema-tree.md) +- [Returns Tokens](returns-tokens.md) +- [Returns Token as per Token ID](returns-token-as-per-tokenid.md) +- [Returns NFTs](returns-nfts.md) +- [Returns NFT as per Serial No.](returns-nft-as-per-serial-no..md) +- [Returns Topics](returns-topics.md) +- [Returns Topic as per Topic ID](returns-topic-as-per-topicid.md) +- [Returns Contracts](returns-contracts.md) +- [Returns Contract as per Message ID](returns-contract-as-per-messageid.md) +- [Returns Modules](returns-modules.md) +- [Returns Module as per Message ID](returns-module-as-per-messageid.md) +- [Returns Tools](returns-tools.md) +- [Returns Tool as per Message ID](returns-tool-as-per-messageid.md) +- [Returns Roles](returns-roles.md) +- [Returns Role as per Message ID](returns-role-as-per-messageid.md) +- [Returns Standard Registries](returns-standard-registries.md) +- [Returns Registry as per Message ID](returns-registry-as-per-messageid.md) +- [Returns Registry Relationships](returns-registry-relationships.md) +- [Returns Registry Users](returns-registry-users.md) +- [Returns Registry User as per Message ID](returns-registry-user-as-per-messageid.md) +- [Retrieve the List of Formulas](retrieve-the-list-of-formulas.md) +- [Retrieve the Formula by Message ID](retrieve-the-formula-by-message-id.md) +- [Retrieve Linked Documents Related to Formula](retrieve-linked-documents-which-are-related-to-formula.md) +- [Returns Search Policy Results](returns-search-policy-results.md) +- [Comparing the Policy Changes as per ID](comparing-the-policy-changes-as-per-id.md) +- [Display the Derivations](display-the-derivations.md) +- [Returns Landing Page Analytics](returns-landing-page-analytics.md) +- [Returns Hedera Network Explorer Settings](returns-hedera-network-explorer-settings.md) +- [Returns Hedera Network](returns-hedera-network.md) +- [Returns Project Coordinates](returns-project-coordinates.md) +- [Adding Policy Data for Priority Loading](adding-policy-data-for-priority-loading.md) +- [Adding Token Data for Priority Loading](adding-token-data-for-priority-loading.md) +- [Adding Topic Data Priority Loading](adding-topic-data-priority-loading.md) +- [Adding Document to Data Priority Loading](adding-document-to-data-priority-loading.md) +- [Returning Topic Data Priority Loading Progress](returning-topic-data-priority-loading-progress.md) +- [Returns Data Loading Progress Result](returns-data-loading-progress-result.md) +- [Attempts to Refresh Linked Files for the Selected Documents](attempts-to-refresh-linked-files-for-the-selected-documents.md) +- [Download File by ID](download-file-by-id.md) +- [Removes a File from IPFS by CID](removes-a-file-from-ipfs-by-cid.md) diff --git a/docs/guardian/map-related-apis/README.md b/docs/guardian/map-related-apis/README.md index ad5adb2686..66f7a49f97 100644 --- a/docs/guardian/map-related-apis/README.md +++ b/docs/guardian/map-related-apis/README.md @@ -1,2 +1,17 @@ # Map Related APIs +Endpoints for retrieving external API keys used by Guardian's map and geospatial features. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `GET` | `/api/v1/map/key` | Returns the map service API key | Yes | +| `GET` | `/api/v1/map/sh` | Returns the Sentinel Hub API key for satellite imagery | Yes | + +## Endpoints + +- [Returning Map API Key](returning-map-api-key.md) +- [Returning Sentinel API Key](returning-sentinel-api-key.md) diff --git a/docs/guardian/notifications/apis-related-to-notification/README.md b/docs/guardian/notifications/apis-related-to-notification/README.md index f9607aeb36..e2b9b181f9 100644 --- a/docs/guardian/notifications/apis-related-to-notification/README.md +++ b/docs/guardian/notifications/apis-related-to-notification/README.md @@ -1,2 +1,23 @@ -# APIs related to Notification +# APIs Related to Notifications +Endpoints for retrieving, reading, and deleting Guardian notifications for the authenticated user. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `GET` | `/api/v1/notifications` | Returns paginated notifications for the current user | Yes | +| `GET` | `/api/v1/notifications/new` | Returns all unread notifications for the current user | Yes | +| `GET` | `/api/v1/notifications/progresses` | Returns active long-running operation progress notifications | Yes | +| `POST` | `/api/v1/notifications/read/all` | Marks all notifications as read | Yes | +| `DELETE` | `/api/v1/notifications/delete/{notificationId}` | Deletes all notifications up to the specified notification | Yes | + +## Endpoints + +- [Get All Notifications](get-all-notifications.md) +- [Get New Notifications](get-new-notifications.md) +- [Get Progresses](get-progresses.md) +- [Read All Notifications](read-all-notifications.md) +- [Delete Notifications](delete-notifications.md) diff --git a/docs/guardian/notifications/apis-related-to-notification/delete-notifications.md b/docs/guardian/notifications/apis-related-to-notification/delete-notifications.md index 39e587bb69..5915daa556 100644 --- a/docs/guardian/notifications/apis-related-to-notification/delete-notifications.md +++ b/docs/guardian/notifications/apis-related-to-notification/delete-notifications.md @@ -1,33 +1,38 @@ # Delete Notifications -{% swagger method="delete" path="" baseUrl="/notifications/delete/{notificationId}" summary="Delete notifications up to this point" %} -{% swagger-description %} -Returns deleted count. -{% endswagger-description %} +**`DELETE /api/v1/notifications/delete/{notificationId}`** -{% swagger-parameter in="path" name="notificationId" type="String" required="true" %} -Notification ID -{% endswagger-parameter %} +Deletes all notifications up to and including the specified notification and returns the count of deleted notifications. -{% swagger-response status="200: OK" description="Successful operation. Suggested next and nested block type respectively." %} -``` -content: - application/json: - schema: - type: number -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +--- -{% endswagger-response %} +## Request -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `notificationId` | string | Yes | The identifier of the notification up to which all notifications are deleted | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +4 ``` -{% endswagger-response %} -{% endswagger %} + +The response is a number representing the count of deleted notifications. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/notifications/apis-related-to-notification/get-all-notifications.md b/docs/guardian/notifications/apis-related-to-notification/get-all-notifications.md index 57dc25dd7d..6abad5bb61 100644 --- a/docs/guardian/notifications/apis-related-to-notification/get-all-notifications.md +++ b/docs/guardian/notifications/apis-related-to-notification/get-all-notifications.md @@ -1,34 +1,55 @@ # Get All Notifications -{% swagger method="get" path="" baseUrl="/notifications" summary="Get all notifications." %} -{% swagger-description %} -Returns all notifications. -{% endswagger-description %} +**`GET /api/v1/notifications`** -{% swagger-response status="200: OK" description="Successful operation. Suggested next and nested block types respectively." %} -``` -headers: - X-Total-Count: - description: Count of notifications - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/NotificationDTO' -``` -{% endswagger-response %} +Returns a paginated list of all notifications for the authenticated user. -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% endswagger-response %} +--- -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +## Request + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `pageIndex` | number | No | 0 | Zero-based page index; the number of pages to skip before starting to collect the result set | +| `pageSize` | number | No | 20 | The number of items to return per page | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +The response includes an `X-Total-Count` header with the total number of notifications, and a JSON array of notification objects in the body. + +**Response Header:** + +| Header | Description | +|--------|-------------| +| `X-Total-Count` | Total count of notifications for the user | + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "title": "Policy published", + "message": "Policy 'GHG Policy v1.0' has been published successfully.", + "read": false, + "type": "INFO", + "userId": "63e3e5e8a01b3c001234abce", + "createDate": "2024-01-15T10:30:00.000Z" + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/notifications/apis-related-to-notification/get-new-notifications.md b/docs/guardian/notifications/apis-related-to-notification/get-new-notifications.md index 6eb3bfa8a1..f30c2d5925 100644 --- a/docs/guardian/notifications/apis-related-to-notification/get-new-notifications.md +++ b/docs/guardian/notifications/apis-related-to-notification/get-new-notifications.md @@ -1,32 +1,45 @@ -# Get new Notifications +# Get New Notifications -{% swagger method="get" path="" baseUrl="/notifications/new" summary="Get new notifications" %} -{% swagger-description %} -Returns new notifications. -{% endswagger-description %} +**`GET /api/v1/notifications/new`** -{% swagger-response status="200: OK" description="Successful operation. Suggested next and nested block types respectively." %} -``` -content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/NotificationDTO' +Returns all unread (new) notifications for the authenticated user along with their total count. -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +--- -{% endswagger-response %} +## Request -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +No parameters required. + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "items": [ + { + "id": "63e3e5e8a01b3c001234abcd", + "title": "Policy published", + "message": "Policy 'GHG Policy v1.0' has been published successfully.", + "read": false, + "type": "INFO", + "userId": "63e3e5e8a01b3c001234abce", + "createDate": "2024-01-15T10:30:00.000Z" + } + ], + "count": 1 +} ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/notifications/apis-related-to-notification/get-progresses.md b/docs/guardian/notifications/apis-related-to-notification/get-progresses.md index 6c712a6f59..ee6eadf53e 100644 --- a/docs/guardian/notifications/apis-related-to-notification/get-progresses.md +++ b/docs/guardian/notifications/apis-related-to-notification/get-progresses.md @@ -1,31 +1,42 @@ # Get Progresses -{% swagger method="get" path="" baseUrl="/notifications/progresses" summary="Get progresses" %} -{% swagger-description %} -Returns progresses -{% endswagger-description %} +**`GET /api/v1/notifications/progresses`** -{% swagger-response status="200: OK" description="Successful operation. Suggested next and nested block types respectively." %} -``` -content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ProgressDTO' -``` -{% endswagger-response %} +Returns all active progress notifications (long-running task statuses) for the authenticated user. -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% endswagger-response %} +--- -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +## Request + +No parameters required. + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "title": "Publishing policy", + "message": "Policy 'GHG Policy v1.0' is being published.", + "progress": 65, + "type": "PROGRESS", + "userId": "63e3e5e8a01b3c001234abce", + "createDate": "2024-01-15T10:30:00.000Z" + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/notifications/apis-related-to-notification/read-all-notifications.md b/docs/guardian/notifications/apis-related-to-notification/read-all-notifications.md index a961fa3095..0231db56f7 100644 --- a/docs/guardian/notifications/apis-related-to-notification/read-all-notifications.md +++ b/docs/guardian/notifications/apis-related-to-notification/read-all-notifications.md @@ -1,31 +1,42 @@ # Read All Notifications -{% swagger method="post" path="" baseUrl="/notifications/read/all" summary="Read all notifications" %} -{% swagger-description %} -Returns new notifications. -{% endswagger-description %} +**`POST /api/v1/notifications/read/all`** -{% swagger-response status="200: OK" description="Successful operation. Suggested next and nested block types respectively." %} -``` -content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/NotificationDTO' -``` -{% endswagger-response %} +Marks all notifications as read for the authenticated user and returns the updated notification collection. -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% endswagger-response %} +--- -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +## Request + +No request body required. + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "title": "Policy published", + "message": "Policy 'GHG Policy v1.0' has been published successfully.", + "read": true, + "type": "INFO", + "userId": "63e3e5e8a01b3c001234abce", + "createDate": "2024-01-15T10:30:00.000Z" + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/project-comparison/project-comparison-apis/README.md b/docs/guardian/project-comparison/project-comparison-apis/README.md index 8b5f2ad9fd..31aaac848e 100644 --- a/docs/guardian/project-comparison/project-comparison-apis/README.md +++ b/docs/guardian/project-comparison/project-comparison-apis/README.md @@ -1,2 +1,21 @@ # Project Comparison APIs +Endpoints for comparing Guardian project documents, VP documents, and searching projects by property filters. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `POST` | `/api/v1/analytics/compare/documents` | Compares two documents and returns the differences | Yes | +| `POST` | `/api/v1/projects/compare/documents` | Compares VP documents across projects | Yes | +| `GET` | `/api/v1/projects/properties` | Returns all project property definitions | Yes | +| `POST` | `/api/v1/projects/search` | Searches for projects matching specified filter parameters | Yes | + +## Endpoints + +- [Comparing Documents](comparing-documents.md) +- [Comparing VP Documents](comparing-vp-documents-v1.md) +- [Retrieves All Properties](retrieves-all-properties.md) +- [Search Projects by Filters](search-projects-by-filters.md) diff --git a/docs/guardian/project-comparison/project-comparison-apis/comparing-documents.md b/docs/guardian/project-comparison/project-comparison-apis/comparing-documents.md index 03a7244c56..7c13afa788 100644 --- a/docs/guardian/project-comparison/project-comparison-apis/comparing-documents.md +++ b/docs/guardian/project-comparison/project-comparison-apis/comparing-documents.md @@ -1,16 +1,56 @@ # Comparing Documents -{% swagger method="post" path="" baseUrl="/analytics/compare/documents" summary="Compare documents. Only users with the Standard Registry role are allowed to make the request." %} -{% swagger-description %} -Compare documents. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /api/v1/analytics/compare/documents`** -{% swagger-parameter in="body" name="documentIds" type="String" required="true" %} -Document Identifiers to compare -{% endswagger-parameter %} +Compares two or more VC documents and returns a detailed field-level comparison result. Only Standard Registry users are allowed to make this request. -{% swagger-response status="200: OK" description="Successful Operation" %} +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.ANALYTIC_DOCUMENT_READ` + +--- + +## Request + +### Request Body + +```json +{ + "documentId1": "63e3e5e8a01b3c001234abcd", + "documentId2": "63e3e5e8a01b3c001234abce" +} +``` + +Alternatively, compare multiple documents at once: + +```json +{ + "documentIds": [ + "63e3e5e8a01b3c001234abcd", + "63e3e5e8a01b3c001234abce" + ] +} ``` + +| Field | Type | Required | Description | +|---------------|--------|----------|--------------------------------------------------------------------------| +| `documentId1` | string | No* | ID of the first document to compare. Required if `documentIds` is absent | +| `documentId2` | string | No* | ID of the second document to compare. Required if `documentIds` is absent | +| `documentIds` | array | No* | Array of document IDs to compare. Required if `documentId1`/`documentId2` are absent | +| `eventsLvl` | number | No | Comparison depth for events | +| `propLvl` | number | No | Comparison depth for properties | +| `childrenLvl` | number | No | Comparison depth for children | +| `idLvl` | number | No | Comparison depth for IDs | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json { "documents": {}, "left": {}, @@ -18,14 +58,19 @@ Document Identifiers to compare "total": {} } ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -{ - "code": 0, - "message": "string" -} -``` -{% endswagger-response %} -{% endswagger %} +| Field | Type | Description | +|-------------|--------|---------------------------------------------| +| `documents` | object | Document metadata for both sides | +| `left` | object | Fields and values from the left document | +| `right` | object | Fields and values from the right document | +| `total` | object | Summary of differences and matches | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Neither document pair nor documentIds array provided | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/project-comparison/project-comparison-apis/comparing-vp-documents-v1.md b/docs/guardian/project-comparison/project-comparison-apis/comparing-vp-documents-v1.md index 9209adbdf7..3051c20b30 100644 --- a/docs/guardian/project-comparison/project-comparison-apis/comparing-vp-documents-v1.md +++ b/docs/guardian/project-comparison/project-comparison-apis/comparing-vp-documents-v1.md @@ -1,5 +1,72 @@ -# Comparing VP Documents - V1 +# Comparing VP Documents -{% openapi src="../../../.gitbook/assets/swagger (2) (1) (1).yaml" path="/projects/compare/documents" method="post" %} -[swagger (2) (1) (1).yaml](<../../../.gitbook/assets/swagger (2) (1) (1).yaml>) -{% endopenapi %} +**`POST /api/v1/projects/compare/documents`** + +Compares two or more VC documents across projects and returns both VC-level and VP-level comparison results. This endpoint does not require authentication. + +--- + +## Request + +### Request Body + +```json +{ + "documentId1": "63e3e5e8a01b3c001234abcd", + "documentId2": "63e3e5e8a01b3c001234abce" +} +``` + +Alternatively, compare multiple documents at once: + +```json +{ + "documentIds": [ + "63e3e5e8a01b3c001234abcd", + "63e3e5e8a01b3c001234abce" + ] +} +``` + +| Field | Type | Required | Description | +|---------------|--------|----------|-------------------------------------------------------------------------------| +| `documentId1` | string | No* | ID of the first document. Required if `documentIds` is absent | +| `documentId2` | string | No* | ID of the second document. Required if `documentIds` is absent | +| `documentIds` | array | No* | Array of document IDs to compare. Required if `documentId1`/`documentId2` are absent | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "projects": { + "documents": {}, + "left": {}, + "right": {}, + "total": {} + }, + "presentations": { + "documents": {}, + "left": {}, + "right": {}, + "total": {} + } +} +``` + +| Field | Type | Description | +|-----------------|--------|------------------------------------------------------| +| `projects` | object | VC document comparison result | +| `presentations` | object | VP (Verifiable Presentation) comparison result | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `422 Unprocessable Entity` | Neither document pair nor documentIds array provided | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/project-comparison/project-comparison-apis/retrieves-all-properties.md b/docs/guardian/project-comparison/project-comparison-apis/retrieves-all-properties.md index 4ebcea89bf..80a5a12969 100644 --- a/docs/guardian/project-comparison/project-comparison-apis/retrieves-all-properties.md +++ b/docs/guardian/project-comparison/project-comparison-apis/retrieves-all-properties.md @@ -1,7 +1,37 @@ -# Retrieves all Properties +# Retrieves All Properties -## Get all properties +**`GET /api/v1/projects/properties`** -{% openapi src="../../../.gitbook/assets/swagger (2) (1) (1).yaml" path="/projects/properties" method="get" %} -[swagger (2) (1) (1).yaml](<../../../.gitbook/assets/swagger (2) (1) (1).yaml>) -{% endopenapi %} +Returns a list of all properties available across project documents. This endpoint does not require authentication. + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +[ + { + "name": "projectName", + "label": "Project Name", + "required": true, + "type": "string" + } +] +``` + +| Field | Type | Description | +|------------|---------|--------------------------------------------| +| `name` | string | Property field name | +| `label` | string | Human-readable label for the property | +| `required` | boolean | Whether the property is required | +| `type` | string | Data type of the property | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/project-comparison/project-comparison-apis/search-projects-by-filters.md b/docs/guardian/project-comparison/project-comparison-apis/search-projects-by-filters.md index eec92b37a9..8f847d6cb5 100644 --- a/docs/guardian/project-comparison/project-comparison-apis/search-projects-by-filters.md +++ b/docs/guardian/project-comparison/project-comparison-apis/search-projects-by-filters.md @@ -1,36 +1,61 @@ -# Search Projects by filters +# Search Projects by Filters -{% swagger method="post" path="" baseUrl="/projects/search" summary="Search projects by filters" %} -{% swagger-description %} -Search projects by filters -{% endswagger-description %} +**`POST /api/v1/projects/search`** -{% swagger-parameter in="body" name="q" type="String" required="true" %} -The question of the methodology -{% endswagger-parameter %} +Searches for projects matching the provided category or policy filters. This endpoint does not require authentication. -{% swagger-response status="200: OK" description="Successful Operation" %} +--- + +## Request + +### Request Body + +```json +{ + "categoryIds": ["63e3e5e8a01b3c001234abcd"], + "policyIds": ["63e3e5e8a01b3c001234abce"] +} ``` + +| Field | Type | Required | Description | +|---------------|--------|----------|--------------------------------------------------------------------------------| +| `categoryIds` | array | No | List of category IDs to filter projects by | +| `policyIds` | array | No | List of policy IDs to filter projects by | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json [ { - "id": "string", - "policyId": "string", - "policyName": "string", - "registered": "string", - "title": "string", - "companyName": "string", - "sectoralScope": "string" + "id": "63e3e5e8a01b3c001234abcd", + "policyId": "63e3e5e8a01b3c001234abce", + "policyName": "Example Policy", + "registered": "2024-01-15T00:00:00.000Z", + "title": "Example Project", + "companyName": "Example Corp", + "sectoralScope": "Energy" } ] ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -{ - "code": 0, - "message": "string" -} -``` -{% endswagger-response %} -{% endswagger %} +| Field | Type | Description | +|-----------------|--------|----------------------------------------------| +| `id` | string | Unique identifier of the project | +| `policyId` | string | ID of the policy this project belongs to | +| `policyName` | string | Name of the associated policy | +| `registered` | string | Registration date of the project (ISO 8601) | +| `title` | string | Project title | +| `companyName` | string | Name of the company that registered the project | +| `sectoralScope` | string | Sectoral scope of the project | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/artifacts/artifacts-apis/README.md b/docs/guardian/standard-registry/artifacts/artifacts-apis/README.md index a989e27ff0..8abd40daae 100644 --- a/docs/guardian/standard-registry/artifacts/artifacts-apis/README.md +++ b/docs/guardian/standard-registry/artifacts/artifacts-apis/README.md @@ -1,2 +1,21 @@ # Artifacts APIs +Endpoints for uploading, retrieving, and deleting policy artifacts — files (schemas, configurations, evidence) attached to Guardian policies. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** Standard Registry role required. + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `GET` | `/api/v1/artifacts` | Returns all artifacts | Yes | +| `POST` | `/api/v1/artifacts/{policyId}` | Uploads new artifacts for the specified policy | Yes | +| `DELETE` | `/api/v1/artifacts/{artifactId}` | Deletes the specified artifact | Yes | + +## Endpoints + +- [Returns All Artifacts](returns-all-artifacts.md) +- [Upload Artifacts](upload-artifacts.md) +- [Delete Artifact](delete-artifact.md) diff --git a/docs/guardian/standard-registry/external-events/README.md b/docs/guardian/standard-registry/external-events/README.md index c8c44037d1..a2c187531f 100644 --- a/docs/guardian/standard-registry/external-events/README.md +++ b/docs/guardian/standard-registry/external-events/README.md @@ -1,27 +1,30 @@ # External Events -### Introduction +Guardian processes tasks asynchronously. As operations complete, it publishes events to an internal NATS message broker. External systems can subscribe to these events to build reliable, event-driven integrations without polling. -Guardian will publish number of events to NATS server to hook into those events , which extends the function that is suitable to the solution. +There are two ways to consume Guardian events: -### Hooks to external event +- **Direct NATS subscription** — connect your own NATS client to the same broker and subscribe to subjects directly. +- **Application Events Module** — a standalone HTTP service (port 3012) that subscribes to NATS on your behalf and forwards events to registered webhooks or a streaming endpoint. See [Application Events Module](monitoring-tools/application-events-module.md). -To hooks into Guardian events, we need to have a client, that is connected to same NATS instance with Guardian and implement the response function for a specific event. +--- -Below is the sample for .NodeJs and in case of other language please refer to [Nats.io](https://nats.io/) for complete documentation. +## Subscription Patterns -#### publish/subscribe events +Guardian events use two NATS interaction patterns. -The events with type=`publish` is publish/subscribe pattern so that the same message can be received by multiple clients. If there are multiple clients make sure it is handled by duplicate message processing. +### Publish / Subscribe + +Events with pattern type `publish` follow the standard pub/sub model. The same message is delivered to every active subscriber. If multiple subscribers are running, ensure your application handles potential duplicate delivery. ```js import { connect, JSONCodec } from "nats"; (async () => { const nc = await connect({ servers: "localhost:4222" }); - const c = JSONCodec(); - const sub = nc.subscribe("externals-events.ipfs_added_file"); + + const sub = nc.subscribe("external-events.token_minted"); (async () => { for await (const m of sub) { @@ -32,47 +35,295 @@ import { connect, JSONCodec } from "nats"; })(); ``` -To get more information please click [https://github.com/nats-io/nats.js#publish-and-subscribe](https://github.com/nats-io/nats.js#publish-and-subscribe) +For more details see the [NATS.js publish/subscribe documentation](https://github.com/nats-io/nats.js#publish-and-subscribe). -#### request/reply events +### Request / Reply -Some event has type=`request` for which we need to subscribe and respond to the event. +Events with pattern type `request` require the subscriber to reply. Guardian waits for your response before proceeding. If no listener is registered, or the listener responds with an error, Guardian continues with the original content unmodified. -#### Example: - -For the before/after IPFS event, if the listener responds an error then IPFS service will be skipped and upload/response the actual content. This same scenario also happens when we do not have listener to an event. For example we can use this to encrypt/decrypt IPFS content file +This pattern is used for IPFS content interception hooks (e.g., encryption/decryption of content before upload or after read). ```js -const responseToIpfsEvent = (type: string, cb: (data: Buffer) => Buffer) => { - const sub = nc.subscribe(type); - console.log("√ Listening to IPFS event: %s", type); - (async () => { - for await (const m of sub) { - console.log(`[${sub.getProcessed()} - ${m.subject}]`); - try { - const payload = c.decode(m.data) as any; - const body = cb(Buffer.from(payload.content, 'base64')); - const responseMessage = { body: body.toString('base64') } - const archResponse = zlib.deflateSync(JSON.stringify(responseMessage)).toString('binary'); - m.respond(StringCodec().encode(archResponse)); - } catch (e) { - // It is important that you should handle the content to make sure that is your encrypted/decrypted, skip if that is system ipds file - const archResponse = zlib.deflateSync(JSON.stringify({ error: e.message })).toString('binary'); - m.respond(StringCodec().encode(archResponse)); - } - - } - console.log("Subscription closed"); - })(); - }; +import { connect, JSONCodec, StringCodec } from "nats"; +import * as zlib from "zlib"; + +(async () => { + const nc = await connect({ servers: "localhost:4222" }); + const c = JSONCodec(); + + const interceptContent = (type, transformFn) => { + const sub = nc.subscribe(type); + console.log("Listening to IPFS event:", type); + + (async () => { + for await (const m of sub) { + try { + const payload = c.decode(m.data); + const transformed = transformFn(Buffer.from(payload.content, "base64")); + const responseMessage = { body: transformed.toString("base64") }; + const compressed = zlib.deflateSync(JSON.stringify(responseMessage)).toString("binary"); + m.respond(StringCodec().encode(compressed)); + } catch (e) { + // Respond with error to signal Guardian to skip interception for this message + const compressed = zlib.deflateSync(JSON.stringify({ error: e.message })).toString("binary"); + m.respond(StringCodec().encode(compressed)); + } + } + })(); + }; + + // Example: intercept IPFS uploads with a custom transform + interceptContent("external-events.ipfs_before_upload_content", (buf) => { + // encrypt or transform buf here, return Buffer + return buf; + }); +})(); +``` + +--- + +## Event Reference + +### Core External Events + +These events are published by Guardian's core services and represent the primary integration surface for external systems. + +| Event Subject | Pattern | Description | +|---|---|---| +| `external-events.token_minted` | publish | A Hedera token was successfully minted | +| `external-events.token_mint_complete` | publish | All token minting operations for a batch are complete | +| `external-events.error_logs` | publish | An error was written to the Guardian logger service | +| `external-events.block_event` | publish | A policy block execution event occurred | +| `external-events.ipfs_added_file` | publish | A file was successfully added to IPFS | +| `external-events.ipfs_before_upload_content` | request | Hook: intercept and optionally transform content before IPFS upload | +| `external-events.ipfs_after_read_content` | request | Hook: intercept and optionally transform content after reading from IPFS | +| `external-events.ipfs_loaded_file` | subscribe | A file load from IPFS has completed | + +--- + +### `external-events.token_minted` + +**Pattern:** publish + +**Trigger:** Guardian successfully mints a Hedera token during policy execution. + +**Payload:** + +```json +{ + "tokenId": "0.0.1554488", + "tokenValue": 10, + "memo": "policy-mint-batch-1" +} +``` + +| Field | Type | Description | +|---|---|---| +| `tokenId` | string | Hedera token identifier (`shard.realm.num`) | +| `tokenValue` | number | Number of tokens minted in this operation | +| `memo` | string | Optional memo string associated with the mint transaction | + +--- + +### `external-events.token_mint_complete` + +**Pattern:** publish + +**Trigger:** All pending token minting operations in a batch have completed. + +**Payload:** + +```json +{ + "tokenValue": 10 +} +``` + +| Field | Type | Description | +|---|---|---| +| `tokenValue` | number | Total number of tokens that were minted in the completed batch | + +--- + +### `external-events.error_logs` + +**Pattern:** publish + +**Trigger:** An error is written to the Guardian logger service by any internal service. + +**Payload:** + +```json +{ + "message": "failed store/add invocation", + "type": "error", + "attributes": { + "service": "guardian-service", + "code": "IPFS_UPLOAD_FAILED" + } +} +``` + +| Field | Type | Description | +|---|---|---| +| `message` | string | Human-readable error description | +| `type` | string | Severity or error category | +| `attributes` | object | Additional contextual attributes from the originating service | + +--- + +### `external-events.block_event` + +**Pattern:** publish + +**Trigger:** A policy block executes an action that produces an external event (e.g., a user submits a form, a document is set, a timer fires). + +**Payload:** + +```json +[ + { + "type": "Set", + "blockUUID": "37c1b465-5261-4626-8972-f367301974a1", + "blockType": "requestVcDocumentBlock", + "blockTag": "applicant_form", + "userId": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "data": { + "documents": [] + } + } +] +``` + +The payload is an array of block event objects. Each object has: + +| Field | Type | Description | +|---|---|---| +| `type` | string | Event type — one of `Run`, `Set`, `TickAggregate`, `TickCron`, `DeleteMember`, `StartCron`, `StopCron`, `SignatureQuorumReachedEvent`, `SignatureSetInsufficientEvent`, `Step`, `Chunk` | +| `blockUUID` | string | Unique identifier of the block that produced this event | +| `blockType` | string | The block's type name (e.g., `requestVcDocumentBlock`, `mintDocumentBlock`) | +| `blockTag` | string | The human-readable tag assigned to the block in the policy editor | +| `userId` | string | Hedera DID of the user who triggered the block action | +| `data` | object | Block-specific payload; structure varies by block type | + +--- + +### `external-events.ipfs_added_file` + +**Pattern:** publish + +**Trigger:** A file (document, schema, artifact) is successfully pinned to IPFS. + +**Payload:** + +```json +{ + "cid": "QmPs2ufs5VQPYGGX1ewEjKSR8zuEmeuWK4GBKFHZjXTCAQ", + "url": "ipfs://QmPs2ufs5VQPYGGX1ewEjKSR8zuEmeuWK4GBKFHZjXTCAQ" +} +``` + +| Field | Type | Description | +|---|---|---| +| `cid` | string | IPFS content identifier (CIDv0) | +| `url` | string | IPFS URI in `ipfs://` scheme | + +--- + +### `external-events.ipfs_before_upload_content` + +**Pattern:** request/reply + +**Trigger:** Guardian is about to upload content to IPFS. The content is delivered as a base64-encoded buffer. + +**Payload received:** + +```json +{ + "content": "" +} +``` + +**Expected reply:** + +Return a zlib-deflated JSON object with the (optionally transformed) content: + +```json +{ + "body": "" +} +``` + +To skip transformation and signal an error, respond with: + +```json +{ + "error": "reason for skipping" +} +``` + +If no listener is registered, or the listener responds with an error, Guardian uploads the original content unchanged. + +> **Note:** This event is a request/reply hook. It is not forwarded by the Application Events Module. Subscribe directly via NATS. + +--- + +### `external-events.ipfs_after_read_content` + +**Pattern:** request/reply + +**Trigger:** Guardian has just read content from IPFS. Use this hook to decrypt or post-process content before Guardian consumes it. + +**Payload received:** + +```json +{ + "content": "" +} +``` + +**Expected reply:** Same structure as `ipfs_before_upload_content`. Return the transformed content or an error object. + +> **Note:** This event is a request/reply hook. It is not forwarded by the Application Events Module. Subscribe directly via NATS. + +--- + +### `external-events.ipfs_loaded_file` + +**Pattern:** subscribe + +**Trigger:** An asynchronous IPFS file load has completed (either successfully or with an error). + +**Payload:** + +```json +{ + "taskId": "be1c8bc2-c100-47c5-af48-46c10b5fde55", + "fileContent": "", + "error": null +} ``` -### External events list +| Field | Type | Description | +|---|---|---| +| `taskId` | string | UUID correlating this result to the original load request | +| `fileContent` | string | Base64-encoded file content; present on success | +| `error` | string \| null | Error message if the load failed; `null` on success | + +> **Note:** This event is not forwarded by the Application Events Module. Subscribe directly via NATS. + +--- + +## Policy Engine Events + +In addition to the core external events above, the Application Events Module also surfaces Guardian's internal policy coordination events. These are emitted on NATS subjects from the `PolicyEvents` and `PolicyEngineEvents` enumerations (e.g., `policy-event-policy-ready`, `policy-engine-event-publish-policies`). + +These events are intended for advanced integrations that need to react to specific policy lifecycle transitions. They are available through the Application Events Module's streaming endpoint and webhook registration. Use **`GET /api/events`** on the Application Events Module to retrieve the complete list of exposed event subjects at runtime. -
eventtypepayloadnotesExample
external-events.token_mintedpublish{ tokenId, tokenValue, memo }Triggered when a token is successfully minted.{
tokenId: '0.0.1554488',
tokenValue: 10
}
external-events.token_mint_completepublish{ tokenValue }Triggered when all tokens have been minted.{
tokenValue: 10
}
external-events.error_logspublish{ message, type, attributes }Triggered when an error is sent to the logger service.{
id: '9b9d1cd0-cff4-467b-a3bc-8866fa1cfd18',
error: 'failed store/add invocation'
}
external-events.block_eventpublish<blockEventData>Represents a block external event.[
{
type: 'Set',
blockUUID: '37c1b465-5261-4626-8972-f367301974a1',
blockType: 'requestVcDocumentBlock',
blockTag: 'bad_token_form',
userId: 'did:hedera:testnet:FF7nFWaMCkHjEfJLtcUQTLRQao9yCCj6mc4MRvgDjStW_0.0.5277702',
data: { documents: [Array] }
}
]
external-events.ipfs_added_filepublish{ cid, url }Triggered when a file is added to IPFS.

{ cid: 'QmPs2ufs5VQPYGGX1ewEjKSR8zuEmeuWK4GBKFHZjXTCAQ',

url: 'ipfs://QmPs2ufs5VQPYGGX1ewEjKSR8zuEmeuWK4GBKFHZjXTCAQ' }

external-events.ipfs_before_upload_content request{content}The base64-encoded content (buffer) to be hooked and modified before uploading to IPFS.{
content: 'eyJAY29udGV4dCI6eyJAdmVyc2lvbiI6MS4xLCJAdm9jYWIiOiJodHRwczovL3czaWQub3JnL3RyYWNlYWJpbGl0eS8jdW5kZWZpbmVkVGVybSIsImlkIjoiQGlkIiwidHlwZSI6IkB0eXBlIiwiYTkwYWU1OWEtNjhhMS00YmY3LWFmNDgtNTRhNzhiNWQwYzI5JjEiOnsiQGlkIjoic2NoZW1hOmE5MGFlNTlhLTY4YTEtNGJmNy1hZjQ4LTU0YTc4YjVkMGMyOSNhOTBhZTU5YS02OGExLTRiZjctYWY0OC01NGE3OGI1ZDBjMjkmMSIsIkBjb250ZXh0Ijp7InBvbGljeUlkIjp7IkB0eXBlIjoiaHR0cHM6Ly93d3cuc2NoZW1hLm9yZy90ZXh0In0sInJlZiI6eyJAdHlwZSI6Imh0dHBzOi8vd3d3LnNjaGVtYS5vcmcvdGV4dCJ9fX19fQ=='
}
external-events.ipfs_after_read_content request{content}The base64-encoded content (buffer) to be modified or processed after reading from IPFS.QmPs2ufs5VQPYGGX1ewEjKSR8zuEmeuWK4GBKFHZjXTCAQ
external-events.ipfs_loaded_filesubscription{ taskId, fileContent, error }Receives an event when a file load is complete.{
taskId: 'be1c8bc2-c100-47c5-af48-46c10b5fde55',
fileContent: 'eyJAY29udGV4dCI6eyJAdmVyc2lvbiI6MS4xLCJAdm9jYWIiOiJodHRwczovL3czaWQub3JnL3RyYWNlYWJpbGl0eS8jdW5kZWZpbmVkVGVybSIsImlkIjoiQGlkIiwidHlwZSI6IkB0eXBlIiwiYTkwYWU1OWEtNjhhMS00YmY3LWFmNDgtNTRhNzhiNWQwYzI5JjEiOnsiQGlkIjoic2NoZW1hOmE5MGFlNTlhLTY4YTEtNGJmNy1hZjQ4LTU0YTc4YjVkMGMyOSNhOTBhZTU5YS02OGExLTRiZjctYWY0OC01NGE3OGI1ZDBjMjkmMSIsIkBjb250ZXh0Ijp7InBvbGljeUlkIjp7IkB0eXBlIjoiaHR0cHM6Ly93d3cuc2NoZW1hLm9yZy90ZXh0In0sInJlZiI6eyJAdHlwZSI6Imh0dHBzOi8vd3d3LnNjaGVtYS5vcmcvdGV4dCJ9fX19fQ',
error: undefined
}
+--- -### Example +## Reference Implementation -This example demonstrates implementation of encryption / decryption of simple IPFS content. +A complete Node.js reference client demonstrating publish/subscribe and request/reply patterns (including IPFS content encryption) is available at: -Please refer to [https://github.com/hashgraph/guardian/blob/main/common/src/mq/sample-external-client.ts](https://github.com/hashgraph/guardian/blob/main/common/src/mq/sample-external-client.ts) +[`common/src/mq/sample-external-client.ts`](https://github.com/hashgraph/guardian/blob/main/common/src/mq/sample-external-client.ts) diff --git a/docs/guardian/standard-registry/external-events/monitoring-tools/README.md b/docs/guardian/standard-registry/external-events/monitoring-tools/README.md index 405dd3e77a..619d57fde9 100644 --- a/docs/guardian/standard-registry/external-events/monitoring-tools/README.md +++ b/docs/guardian/standard-registry/external-events/monitoring-tools/README.md @@ -1,2 +1,25 @@ # Monitoring Tools +Guardian's monitoring tools provide infrastructure for external systems to observe and react to Guardian's internal event stream without requiring a direct NATS connection. + +## Application Events Module + +The [Application Events Module](application-events-module.md) is a standalone HTTP service (port `3012`) that: + +- Subscribes to all Guardian NATS event subjects on startup +- Exposes a REST API for registering and managing webhooks +- Delivers events to registered webhook URLs via HTTP POST +- Provides a streaming JSON endpoint for real-time event consumption + +| Capability | Endpoint | +|---|---| +| Register a webhook | `POST /api/webhooks` | +| List registered webhooks | `GET /api/webhooks` | +| Retrieve a single webhook | `GET /api/webhooks/{id}` | +| Update a webhook | `PUT /api/webhooks/{id}` | +| Delete a webhook | `DELETE /api/webhooks/{id}` | +| List all available event subjects | `GET /api/events` | +| Subscribe to live event stream | `GET /api/events/subscribe` | +| Interactive API documentation | `GET /api-docs` | + +For full details see [Application Events Module](application-events-module.md). diff --git a/docs/guardian/standard-registry/external-events/monitoring-tools/application-events-module.md b/docs/guardian/standard-registry/external-events/monitoring-tools/application-events-module.md index 6e0b0ca6c8..b40920c1e7 100644 --- a/docs/guardian/standard-registry/external-events/monitoring-tools/application-events-module.md +++ b/docs/guardian/standard-registry/external-events/monitoring-tools/application-events-module.md @@ -1,9 +1,380 @@ -# Application-events module +# Application Events Module -The application-events module provide resources in order to integrate the external events described [here](https://docs.hedera.com/guardian/guardian/standard-registry/external-events) to the external application. +The Application Events Module is a standalone service that bridges Guardian's internal NATS event bus and external HTTP-based systems. It removes the need for external integrators to operate their own NATS client by providing: -An API is provided to allow registration for webhooks which is described in this port: [http://localhost:3012/api-docs](http://localhost:3012/api-docs) +- A **webhook registry** — register HTTP endpoints that receive event payloads via POST. +- A **streaming endpoint** — consume all events as a chunked JSON stream over HTTP. +- A **REST API** — manage webhook subscriptions and enumerate available event subjects. -The user can consume the available events, and register webhooks specifying these events. +The service runs on port `3012` by default. Interactive Swagger documentation is available at `http://localhost:3012/api-docs`. -And for streaming consuming resources, we provide an endpoint which could be consuming by streaming technologies: [http://localhost:3012/api/events/subscribe](http://localhost:3012/api/events/subscribe) +--- + +## Architecture + +``` +Guardian Services + │ + │ publishes events to + ▼ + NATS Broker + │ + │ subscribed by + ▼ +Application Events Module (port 3012) + │ + ├──► Registered Webhooks (HTTP POST to your URLs) + │ + └──► GET /api/events/subscribe (chunked JSON stream) +``` + +On startup the module: + +1. Connects to MongoDB to load persisted webhook registrations. +2. Connects to the NATS broker and subscribes to all exposed event subjects. +3. For each received message, delivers the payload to all matching registered webhooks. + +--- + +## Quickstart: Subscribe via Streaming Endpoint + +The simplest way to consume events is the streaming endpoint. It returns a chunked JSON array that stays open as long as the connection is alive. Each element is a JSON object with the event subject and payload. + +```bash +curl -N http://localhost:3012/api/events/subscribe +``` + +Example stream output: + +```json +[ +{"subject":"external-events.token_minted","payload":{"tokenId":"0.0.1554488","tokenValue":10}}, +{"subject":"external-events.ipfs_added_file","payload":{"cid":"QmPs2ufs5VQPYGGX1ewEjKSR8zuEmeuWK4GBKFHZjXTCAQ","url":"ipfs://QmPs2ufs5VQPYGGX1ewEjKSR8zuEmeuWK4GBKFHZjXTCAQ"}}, +``` + +The stream remains open. When the NATS connection closes, the array is terminated with `{"connection":"closed"}]`. + +--- + +## Quickstart: Register a Webhook + +**Step 1 — Retrieve the list of available event subjects:** + +```bash +curl http://localhost:3012/api/events +``` + +Returns a JSON array of all event subject strings the module is currently forwarding, for example: + +```json +[ + "external-events.token_minted", + "external-events.token_mint_complete", + "external-events.error_logs", + "external-events.block_event", + "external-events.ipfs_added_file", + "policy-event-policy-ready", + "policy-engine-event-publish-policies", + ... +] +``` + +**Step 2 — Register a webhook for one or more event subjects:** + +```bash +curl -X POST http://localhost:3012/api/webhooks \ + -H "Content-Type: application/json" \ + -d '{ + "url": "https://your-system.example.com/guardian-events", + "events": [ + "external-events.token_minted", + "external-events.block_event" + ] + }' +``` + +**Response `201 Created`:** + +```json +{ + "id": "63e3e5e8a01b3c001234abcd" +} +``` + +**Step 3 — Receive events at your endpoint:** + +When Guardian mints a token, your endpoint will receive an HTTP POST: + +```json +{ + "tokenId": "0.0.1554488", + "tokenValue": 10, + "memo": "policy-mint" +} +``` + +--- + +## REST API Reference + +### List Available Event Subjects + +**`GET /api/events`** + +Returns the complete list of NATS event subjects the module is currently subscribed to and will forward to webhooks or the streaming endpoint. + +**Status:** `200 OK` + +```json +[ + "external-events.token_minted", + "external-events.token_mint_complete", + "external-events.error_logs", + "external-events.block_event", + "external-events.ipfs_added_file", + "policy-event-generate-policy", + "policy-event-policy-ready", + "..." +] +``` + +--- + +### Subscribe to Event Stream + +**`GET /api/events/subscribe`** + +Opens a persistent chunked HTTP response. Each chunk is a JSON object: + +```json +{"subject": "", "payload": } +``` + +The response uses `Transfer-Encoding: chunked` and `Content-Type: application/json`. The stream starts with `[` and each element is separated by `,\n`. The array is closed when the NATS connection terminates. + +**Status:** `200 OK` (streaming) + +--- + +### Register a Webhook + +**`POST /api/webhooks`** + +Persists a new webhook registration. The module will HTTP POST the event payload to `url` whenever an event matching one of the registered `events` subjects is received. + +**Request Body:** + +```json +{ + "url": "https://your-system.example.com/events", + "events": [ + "external-events.token_minted", + "external-events.block_event" + ] +} +``` + +| Field | Type | Required | Description | +|---|---|---|---| +| `url` | string | Yes | Publicly reachable HTTPS URL that accepts POST requests | +| `events` | string[] | No | List of event subjects to subscribe to; omit or pass `[]` to receive all events | + +**Status:** `201 Created` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd" +} +``` + +| Field | Description | +|---|---| +| `id` | MongoDB ObjectId of the created webhook registration | + +**Error Responses:** + +| Status | Description | +|---|---| +| `400 Bad Request` | Request body failed schema validation | +| `500 Internal Server Error` | Database write failed | + +--- + +### List Registered Webhooks + +**`GET /api/webhooks`** + +Returns all persisted webhook registrations. + +**Status:** `200 OK` + +```json +[ + { + "_id": "63e3e5e8a01b3c001234abcd", + "url": "https://your-system.example.com/events", + "events": ["external-events.token_minted"], + "createdAt": "2026-04-06T08:00:00.000Z" + } +] +``` + +--- + +### Retrieve a Webhook + +**`GET /api/webhooks/{id}`** + +Returns a single webhook registration by its MongoDB ObjectId. + +**Path Parameters:** + +| Parameter | Type | Required | Description | +|---|---|---|---| +| `id` | string | Yes | MongoDB ObjectId of the webhook | + +**Status:** `200 OK` + +```json +{ + "_id": "63e3e5e8a01b3c001234abcd", + "url": "https://your-system.example.com/events", + "events": ["external-events.token_minted"], + "createdAt": "2026-04-06T08:00:00.000Z" +} +``` + +**Error Responses:** + +| Status | Description | +|---|---| +| `404 Not Found` | No webhook exists with the given `id` | + +--- + +### Update a Webhook + +**`PUT /api/webhooks/{id}`** + +Replaces the `url` and `events` fields of an existing webhook registration. + +**Path Parameters:** + +| Parameter | Type | Required | Description | +|---|---|---|---| +| `id` | string | Yes | MongoDB ObjectId of the webhook | + +**Request Body:** + +```json +{ + "url": "https://your-system.example.com/new-endpoint", + "events": [ + "external-events.token_minted", + "external-events.token_mint_complete" + ] +} +``` + +| Field | Type | Required | Description | +|---|---|---|---| +| `url` | string | Yes | Updated destination URL | +| `events` | string[] | Yes | Updated list of event subjects | + +**Status:** `204 No Content` + +**Error Responses:** + +| Status | Description | +|---|---| +| `400 Bad Request` | Request body failed schema validation | +| `404 Not Found` | No webhook exists with the given `id` | + +--- + +### Delete a Webhook + +**`DELETE /api/webhooks/{id}`** + +Removes a webhook registration. The module will immediately stop forwarding events to the associated URL. + +**Path Parameters:** + +| Parameter | Type | Required | Description | +|---|---|---|---| +| `id` | string | Yes | MongoDB ObjectId of the webhook to delete | + +**Status:** `204 No Content` + +--- + +## Available Event Subjects + +The module exposes all events from three sources, minus internal request/reply hooks that are not suitable for HTTP delivery. Use `GET /api/events` to retrieve the live list. The categories are: + +### Core External Events + +| Subject | Description | +|---|---| +| `external-events.token_minted` | Token successfully minted | +| `external-events.token_mint_complete` | Mint batch complete | +| `external-events.error_logs` | Error written to Guardian logger | +| `external-events.block_event` | Policy block execution event | +| `external-events.ipfs_added_file` | File pinned to IPFS | + +> The following subjects are **excluded** from webhook/stream delivery because they are request/reply hooks requiring a synchronous NATS response: +> `external-events.ipfs_before_upload_content`, `external-events.ipfs_after_read_content`, `external-events.ipfs_loaded_file` + +### Policy Coordination Events (selected) + +| Subject | Description | +|---|---| +| `policy-event-generate-policy` | Policy instance generation started | +| `policy-event-policy-ready` | Policy instance is ready to serve requests | +| `policy-event-policy-start-error` | Policy failed to start | +| `policy-event-delete-policy` | Policy instance deleted | +| `policy-event-block-update-broadcast` | A block's state changed and UI should refresh | +| `policy-event-mrv-data` | MRV (measurement, reporting, verification) data received | +| `policy-event-record-update-broadcast` | Recording state changed | + +### Policy Engine Events (selected) + +| Subject | Description | +|---|---| +| `policy-engine-event-create-policies` | New policy created | +| `policy-engine-event-publish-policies` | Policy published to Hedera | +| `policy-engine-event-dry-run-policies` | Policy entered dry-run mode | +| `policy-engine-event-draft-policies` | Policy reverted to draft | +| `policy-engine-event-delete-policy-async` | Async policy deletion started | +| `policy-engine-event-migrate-data` | Policy data migration started | +| `policy-engine-event-receive-external-data` | External data submitted to a running policy | + +The full enumeration of all policy coordination and engine event subjects is defined in: +- [`interfaces/src/type/messages/policy-events.ts`](https://github.com/hashgraph/guardian/blob/main/interfaces/src/type/messages/policy-events.ts) +- [`interfaces/src/type/messages/policy-engine-events.ts`](https://github.com/hashgraph/guardian/blob/main/interfaces/src/type/messages/policy-engine-events.ts) + +--- + +## Webhook Delivery + +When an event is received on a subscribed NATS subject, the module iterates over all registered webhooks whose `events` array includes that subject and performs an HTTP POST to each registered URL. + +- **Method:** `POST` +- **Content-Type:** `application/json` +- **Body:** The raw event payload (the object published on NATS) + +Delivery is best-effort. If a webhook URL returns an error or times out, the failure is logged and the module moves on. There is no built-in retry mechanism — design your endpoint to be idempotent and implement your own retry handling if required. + +--- + +## Configuration + +The module is configured via environment variables. The key variables are: + +| Variable | Default | Description | +|---|---|---| +| `PORT` | `3012` | HTTP port the service binds to | +| `MONGODB_URI` | — | MongoDB connection string for webhook persistence | +| `MQ_ADDRESS` | — | NATS broker address (e.g., `nats://localhost:4222`) | + +Refer to the `application-events/.env.example` file in the repository for the complete list. diff --git a/docs/guardian/standard-registry/external-events/send-data-using-the-external-data-apis/README.md b/docs/guardian/standard-registry/external-events/send-data-using-the-external-data-apis/README.md index 86f61ddd81..e1647e3566 100644 --- a/docs/guardian/standard-registry/external-events/send-data-using-the-external-data-apis/README.md +++ b/docs/guardian/standard-registry/external-events/send-data-using-the-external-data-apis/README.md @@ -1,2 +1,15 @@ -# Send Data using the External Data APIs +# Send Data Using the External Data APIs +Endpoint for submitting data from an external source directly to a running Guardian policy block. Used to feed MRV or other external data into a policy workflow. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `POST` | `/api/v1/external` | Sends data from an external source to the matching policy block by owner and block tag | No | + +## Endpoints + +- [Sends Data from an External Source](sends-data-from-an-external-source.md) diff --git a/docs/guardian/standard-registry/import-export-in-excel/import-export-schemas-policies-apis/README.md b/docs/guardian/standard-registry/import-export-in-excel/import-export-schemas-policies-apis/README.md index d804c27657..bf3db7a0e4 100644 --- a/docs/guardian/standard-registry/import-export-in-excel/import-export-schemas-policies-apis/README.md +++ b/docs/guardian/standard-registry/import-export-in-excel/import-export-schemas-policies-apis/README.md @@ -1,2 +1,33 @@ -# Import/Export Schemas/Policies APIs +# Import / Export Schemas and Policies via Excel APIs +Endpoints for importing and exporting Guardian policies and schemas using Excel (`.xlsx`) files. Useful for bulk data entry and schema design using spreadsheet tools. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** Standard Registry role required. + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `GET` | `/api/v1/policies/{policyId}/export/xlsx` | Exports a policy as an Excel file | Yes | +| `POST` | `/api/v1/policies/import/xlsx` | Imports a policy from an Excel file | Yes | +| `POST` | `/api/v1/policies/push/import/xlsx` | Imports a policy from an Excel file asynchronously | Yes | +| `POST` | `/api/v1/policies/import/xlsx/preview` | Previews a policy from an Excel file | Yes | +| `GET` | `/api/v1/schemas/{schemaId}/export/xlsx` | Exports a schema as an Excel file | Yes | +| `POST` | `/api/v1/schemas/import/xlsx` | Imports a schema from an Excel file | Yes | +| `POST` | `/api/v1/schemas/push/import/xlsx` | Imports a schema from an Excel file asynchronously | Yes | +| `POST` | `/api/v1/schemas/import/xlsx/preview` | Previews a schema from an Excel file | Yes | +| `GET` | `/api/v1/schemas` | Returns a list of schemas | Yes | + +## Endpoints + +- [Exporting Policy to Excel](exporting-policy-to-excel.md) +- [Import Policy from Excel File](import-policy-from-excel-file.md) +- [Import Policy from Excel File Asynchronously](import-policy-from-excel-file-asynchronously.md) +- [Policy Preview from Excel File](policy-preview-from-excel-file.md) +- [Returns Schema in Excel File Format](returns-schema-in-excel-file-format.md) +- [Imports New Schema from Excel File](imports-new-schema-from-excel-file.md) +- [Imports New Schema from Excel File Asynchronously](imports-new-schema-from-excel-file-asynchronously.md) +- [Previews Schema from Excel File](previews-schema-from-excel-file.md) +- [Returns List of Schemas](returns-list-of-schemas.md) diff --git a/docs/guardian/standard-registry/policies/auto-suggestion/auto-suggestion-apis/README.md b/docs/guardian/standard-registry/policies/auto-suggestion/auto-suggestion-apis/README.md index 191e832a26..aa5d4811bf 100644 --- a/docs/guardian/standard-registry/policies/auto-suggestion/auto-suggestion-apis/README.md +++ b/docs/guardian/standard-registry/policies/auto-suggestion/auto-suggestion-apis/README.md @@ -1,2 +1,21 @@ -# Auto Suggestion APIs +# Auto-Suggestion APIs +Endpoints for retrieving AI-powered block type suggestions during policy authoring and managing the auto-suggestion configuration. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** Standard Registry role required. + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `POST` | `/api/v1/suggestions` | Returns the next and nested suggested block types for the current policy context | Yes | +| `GET` | `/api/v1/suggestions/config` | Returns the current auto-suggestion configuration | Yes | +| `POST` | `/api/v1/suggestions/config` | Updates the auto-suggestion configuration | Yes | + +## Endpoints + +- [Get Next and Nested Suggested Block Types](get-next-and-nested-suggested-block-types.md) +- [Get Suggestions Configuration](get-suggestions-configuration.md) +- [Set Suggestions Configuration](set-suggestions-configuration.md) diff --git a/docs/guardian/standard-registry/policies/auto-suggestion/auto-suggestion-apis/get-next-and-nested-suggested-block-types.md b/docs/guardian/standard-registry/policies/auto-suggestion/auto-suggestion-apis/get-next-and-nested-suggested-block-types.md index 18b512a7f2..3132085a09 100644 --- a/docs/guardian/standard-registry/policies/auto-suggestion/auto-suggestion-apis/get-next-and-nested-suggested-block-types.md +++ b/docs/guardian/standard-registry/policies/auto-suggestion/auto-suggestion-apis/get-next-and-nested-suggested-block-types.md @@ -1,42 +1,55 @@ -# Get next and nested suggested block types +# Get Next and Nested Suggested Block Types -{% swagger method="post" path="" baseUrl="/suggestions" summary="Get next and nested suggested block types" %} -{% swagger-description %} -Get next and nested suggested block types. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /api/v1/suggestions`** -{% swagger-parameter in="body" required="true" %} -Object that contains suggestions input -{% endswagger-parameter %} +Returns the suggested next and nested block types based on the current policy configuration context. Only Standard Registry users are allowed to make this request. -{% swagger-response status="200: OK" description="Successful operation. Suggested next and nested block types respectively." %} -``` -content: - application/json: - schema: - type: object - properties: - next: - type: string - nested: - type: string -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +**Permission:** `Permissions.SUGGESTIONS_SUGGESTIONS_READ` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} +## Request -{% endswagger-response %} +### Request Body -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} +```json +{ + "blockType": "requestVcDocumentBlock", + "children": [] +} ``` -content: - application/json: - schema: - $ref: "#/components/schemas/Error" + +| Field | Type | Required | Description | +|-------------|--------|----------|------------------------------------------------------| +| `blockType` | string | Yes | The current block type to base suggestions on | +| `children` | array | No | Current children blocks for nested suggestions | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "next": "sendToGuardianBlock", + "nested": "calculateContainerBlock" +} ``` -{% endswagger-response %} -{% endswagger %} + +| Field | Type | Description | +|----------|--------|--------------------------------------| +| `next` | string | Suggested next block type | +| `nested` | string | Suggested nested block type | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/auto-suggestion/auto-suggestion-apis/get-suggestions-configuration.md b/docs/guardian/standard-registry/policies/auto-suggestion/auto-suggestion-apis/get-suggestions-configuration.md index ed9d5a5142..f2810ff9a5 100644 --- a/docs/guardian/standard-registry/policies/auto-suggestion/auto-suggestion-apis/get-suggestions-configuration.md +++ b/docs/guardian/standard-registry/policies/auto-suggestion/auto-suggestion-apis/get-suggestions-configuration.md @@ -1,38 +1,44 @@ -# Get suggestions configuration +# Get Suggestions Configuration -{% swagger method="get" path="" baseUrl="/suggestions/config" summary="Get suggestions config" %} -{% swagger-description %} -Get suggestions config. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`GET /api/v1/suggestions/config`** -{% swagger-response status="200: OK" description="Successful operation. Response suggestions config." %} -``` -content: - application/json: - schema: - type: object - properties: - items: - type: array - items: - $ref: "#/components/schemas/SuggestionsOrderPriority" -``` -{% endswagger-response %} +Returns the current auto-suggestion priority order configuration. Only Standard Registry users are allowed to make this request. -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% endswagger-response %} +**Permission:** `Permissions.SUGGESTIONS_SUGGESTIONS_READ` -{% swagger-response status="403: Forbidden" description="Forbidden" %} +--- -{% endswagger-response %} +## Response -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: "#/components/schemas/Error" +### Success Response + +**Status:** `200 OK` + +```json +{ + "items": [ + { + "id": "63e3e5e8a01b3c001234abcd", + "blockType": "requestVcDocumentBlock", + "order": 1 + } + ] +} ``` -{% endswagger-response %} -{% endswagger %} + +| Field | Type | Description | +|----------------|--------|-----------------------------------------------------| +| `items` | array | List of suggestion priority configuration entries | +| `items[].id` | string | Unique identifier of the configuration entry | +| `items[].blockType` | string | Block type for this priority entry | +| `items[].order` | number | Priority order (lower number = higher priority) | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/auto-suggestion/auto-suggestion-apis/set-suggestions-configuration.md b/docs/guardian/standard-registry/policies/auto-suggestion/auto-suggestion-apis/set-suggestions-configuration.md index f5ef74e2b8..1dfe4b5647 100644 --- a/docs/guardian/standard-registry/policies/auto-suggestion/auto-suggestion-apis/set-suggestions-configuration.md +++ b/docs/guardian/standard-registry/policies/auto-suggestion/auto-suggestion-apis/set-suggestions-configuration.md @@ -1,42 +1,71 @@ -# Set suggestions configuration +# Set Suggestions Configuration -{% swagger method="post" path="" baseUrl="/suggestions/config" summary="Set suggestions config" %} -{% swagger-description %} -Set suggestions config. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /api/v1/suggestions/config`** -{% swagger-parameter in="body" type="Object" required="true" %} -Object that contains suggestions priority order array. -{% endswagger-parameter %} +Sets the auto-suggestion priority order configuration. Only Standard Registry users are allowed to make this request. -{% swagger-response status="201: Created" description="Successful operation. Response set suggestions priority order array." %} -``` -content: - application/json: - schema: - type: object - properties: - items: - type: array - items: - $ref: "#/components/schemas/SuggestionsOrderPriority" -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +**Permission:** `Permissions.SUGGESTIONS_SUGGESTIONS_UPDATE` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} +## Request -{% endswagger-response %} +### Request Body -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} +```json +{ + "items": [ + { + "blockType": "requestVcDocumentBlock", + "order": 1 + }, + { + "blockType": "sendToGuardianBlock", + "order": 2 + } + ] +} ``` -content: - application/json: - schema: - $ref: "#/components/schemas/Error" + +| Field | Type | Required | Description | +|---------------------|--------|----------|-----------------------------------------------------| +| `items` | array | Yes | List of suggestion priority configuration entries | +| `items[].blockType` | string | Yes | Block type for this priority entry | +| `items[].order` | number | Yes | Priority order (lower number = higher priority) | + +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +```json +{ + "items": [ + { + "id": "63e3e5e8a01b3c001234abcd", + "blockType": "requestVcDocumentBlock", + "order": 1 + } + ] +} ``` -{% endswagger-response %} -{% endswagger %} + +| Field | Type | Description | +|---------------------|--------|-----------------------------------------------------| +| `items` | array | The saved suggestion priority configuration | +| `items[].id` | string | Unique identifier of the configuration entry | +| `items[].blockType` | string | Block type for this priority entry | +| `items[].order` | number | Priority order (lower number = higher priority) | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/auto-testing-of-the-policies/auto-testing-policies-apis/README.md b/docs/guardian/standard-registry/policies/auto-testing-of-the-policies/auto-testing-policies-apis/README.md index e62dd1c48d..6b49f2137a 100644 --- a/docs/guardian/standard-registry/policies/auto-testing-of-the-policies/auto-testing-policies-apis/README.md +++ b/docs/guardian/standard-registry/policies/auto-testing-of-the-policies/auto-testing-policies-apis/README.md @@ -1,2 +1,27 @@ -# Auto Testing Policies APIs +# Auto-Testing Policies APIs +Endpoints for adding, running, managing, and retrieving the results of automated policy tests in Guardian. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** Standard Registry role required. + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `POST` | `/api/v1/policies/{policyId}/test` | Adds a new test to the policy | Yes | +| `GET` | `/api/v1/policies/{policyId}/test/{testId}` | Returns a policy test by ID | Yes | +| `DELETE` | `/api/v1/policies/{policyId}/test/{testId}` | Deletes the specified test | Yes | +| `POST` | `/api/v1/policies/{policyId}/test/{testId}/run` | Starts running the policy test | Yes | +| `POST` | `/api/v1/policies/{policyId}/test/{testId}/stop` | Stops the running test | Yes | +| `GET` | `/api/v1/policies/{policyId}/test/{testId}/details` | Returns details of the most recent test run | Yes | + +## Endpoints + +- [Adding New Test to the Policy](adding-new-test-to-the-policy.md) +- [Returning Policy Test by ID](returning-policy-test-by-id.md) +- [Deleting the Specified Test](deleting-the-specified-test.md) +- [Running the Policy Test](running-the-policy-test.md) +- [Stopping the Specified Test](stopping-the-specified-test.md) +- [Returning Details of the Most Recent Test Run](returning-details-of-the-most-recent-test-run.md) diff --git a/docs/guardian/standard-registry/policies/block-policy-discoverability/search-block-apis/README.md b/docs/guardian/standard-registry/policies/block-policy-discoverability/search-block-apis/README.md index 56841d3fb3..e0d0b30864 100644 --- a/docs/guardian/standard-registry/policies/block-policy-discoverability/search-block-apis/README.md +++ b/docs/guardian/standard-registry/policies/block-policy-discoverability/search-block-apis/README.md @@ -1,2 +1,15 @@ # Search Block APIs +Endpoint for discovering policy blocks that match a given block's configuration — used for policy discoverability and deduplication. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `POST` | `/api/v1/analytics/search/block` | Searches for blocks with matching configurations across all policies | Yes | + +## Endpoints + +- [Searching Same Blocks](searching-same-blocks.md) diff --git a/docs/guardian/standard-registry/policies/block-policy-discoverability/search-policy-apis/README.md b/docs/guardian/standard-registry/policies/block-policy-discoverability/search-policy-apis/README.md index 7d7b2f9b74..26d2b35ba2 100644 --- a/docs/guardian/standard-registry/policies/block-policy-discoverability/search-policy-apis/README.md +++ b/docs/guardian/standard-registry/policies/block-policy-discoverability/search-policy-apis/README.md @@ -1,2 +1,15 @@ # Search Policy APIs +Endpoint for searching Guardian policies by content similarity or metadata — used for policy discoverability. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `POST` | `/api/v1/analytics/search/policies` | Searches for policies matching the specified criteria | Yes | + +## Endpoints + +- [Search Policy](search-policy.md) diff --git a/docs/guardian/standard-registry/policies/document-comparison/document-comparison-apis/README.md b/docs/guardian/standard-registry/policies/document-comparison/document-comparison-apis/README.md index 4a192cdd6d..16c8e3004f 100644 --- a/docs/guardian/standard-registry/policies/document-comparison/document-comparison-apis/README.md +++ b/docs/guardian/standard-registry/policies/document-comparison/document-comparison-apis/README.md @@ -1,2 +1,17 @@ # Document Comparison APIs +Endpoints for comparing Guardian VC documents and exporting the comparison results. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `POST` | `/api/v1/analytics/compare/documents` | Compares two VC documents and returns the differences | Yes | +| `GET` | `/api/v1/analytics/compare/documents/export` | Exports document comparison results as a file | Yes | + +## Endpoints + +- [Compare Documents](compare-documents.md) +- [Export Comparison Results](export-comparison-results.md) diff --git a/docs/guardian/standard-registry/policies/dry-run/dry-run-mode-using-apis/README.md b/docs/guardian/standard-registry/policies/dry-run/dry-run-mode-using-apis/README.md index 873dc1e9ed..0ab2c11052 100644 --- a/docs/guardian/standard-registry/policies/dry-run/dry-run-mode-using-apis/README.md +++ b/docs/guardian/standard-registry/policies/dry-run/dry-run-mode-using-apis/README.md @@ -1,2 +1,41 @@ -# Dry Run Mode using APIs +# Dry-Run Mode APIs +Endpoints for running a Guardian policy in dry-run (simulation) mode. Dry-run mode allows testing a policy workflow with virtual users and documents without making any Hedera transactions or persistent changes. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** Standard Registry role required. + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `GET` | `/api/v1/policies/{policyId}/dry-run/users` | Returns all virtual users for the dry-run instance | Yes | +| `POST` | `/api/v1/policies/{policyId}/dry-run/user` | Creates a new virtual user | Yes | +| `POST` | `/api/v1/policies/{policyId}/dry-run/login` | Logs in as a virtual user | Yes | +| `POST` | `/api/v1/policies/{policyId}/dry-run/restart` | Restarts the policy dry-run execution | Yes | +| `GET` | `/api/v1/policies/{policyId}/dry-run/transactions` | Returns the list of dry-run transactions | Yes | +| `GET` | `/api/v1/policies/{policyId}/dry-run/artifacts` | Returns the list of dry-run artifacts | Yes | +| `GET` | `/api/v1/policies/{policyId}/dry-run/ipfs` | Returns the list of IPFS files created in dry-run | Yes | +| `DELETE` | `/api/v1/policies/{policyId}/draft` | Returns the policy to draft/editing state | Yes | +| `GET` | `/api/v1/policies/{policyId}/save-points` | Returns all savepoints for the dry-run session | Yes | +| `POST` | `/api/v1/policies/{policyId}/save-points` | Creates a new savepoint | Yes | +| `GET` | `/api/v1/policies/{policyId}/save-points/{savepointId}` | Returns the savepoint state | Yes | +| `POST` | `/api/v1/policies/{policyId}/save-points/{savepointId}` | Restores a savepoint | Yes | +| `DELETE` | `/api/v1/policies/{policyId}/save-points/{savepointId}` | Deletes a savepoint | Yes | + +## Endpoints + +- [Returning All Virtual Users](returning-all-virtual-users.md) +- [Creating Virtual Account](creating-virtual-account.md) +- [Logging Virtual User](logging-virtual-user.md) +- [Restarting the Execution of Policy](restarting-the-execution-of-policy.md) +- [Returns List of Transactions](returns-list-of-transactions.md) +- [Returns List of Artifacts](returns-list-of-artifacts.md) +- [Returns List of IPFS Files](returns-list-of-ipfs-files.md) +- [Returning Policy to Editing](returning-policy-to-editing.md) +- [Running Policy Without Making Any Changes](running-policy-without-making-any-changes.md) +- [Returns Savepoint State](returns-savepoint-state.md) +- [Create Savepoint](create-savepoint.md) +- [Restoring Savepoint](restoring-savepoint.md) +- [Deletes Savepoint](deletes-savepoint.md) diff --git a/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/create-a-new-formula-import-from-a-file.md b/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/create-a-new-formula-import-from-a-file.md index dcaa1a6cb9..c5c63e7316 100644 --- a/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/create-a-new-formula-import-from-a-file.md +++ b/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/create-a-new-formula-import-from-a-file.md @@ -1,5 +1,55 @@ -# Create a new formula (import) from a file +# Create a New Formula (Import) from a File -{% swagger src="../../../../../.gitbook/assets/swagger (1).yaml" path="/formulas/{policyId}/import/file" method="post" %} -[swagger (1).yaml](<../../../../../.gitbook/assets/swagger (1).yaml>) -{% endswagger %} +**`POST /api/v1/formulas/{policyId}/import/file`** + +Imports a new formula from a ZIP file and links it to the specified policy. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.FORMULAS_FORMULA_CREATE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `policyId` | string | Yes | ID of the policy to associate with the imported formula | + +### Request Body + +Binary ZIP file containing the formula export. + +**Content-Type:** `application/zip` + +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "c4a3b2d1-e5f6-7890-abcd-ef1234567890", + "name": "Carbon Credit Calculator", + "description": "Calculates carbon credits based on emission factors", + "status": "DRAFT", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "policyId": "63e3e5e8a01b3c001234abcd", + "config": {} +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `400 Bad Request` | Malformed or missing ZIP file | +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/creating-a-new-formula.md b/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/creating-a-new-formula.md index 07f0425752..4766d9c92b 100644 --- a/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/creating-a-new-formula.md +++ b/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/creating-a-new-formula.md @@ -1,5 +1,62 @@ -# Creating a new formula +# Creating a New Formula -{% swagger src="../../../../../.gitbook/assets/swagger (1).yaml" path="/formulas" method="post" %} -[swagger (1).yaml](<../../../../../.gitbook/assets/swagger (1).yaml>) -{% endswagger %} +**`POST /api/v1/formulas`** + +Creates a new formula and persists it to the database. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.FORMULAS_FORMULA_CREATE` + +--- + +## Request + +### Request Body + +```json +{ + "name": "Carbon Credit Calculator", + "description": "Calculates carbon credits based on emission factors", + "policyId": "63e3e5e8a01b3c001234abcd", + "config": {} +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | Yes | Human-readable formula name | +| `description` | string | No | Description of the formula's purpose | +| `policyId` | string | No | ID of the policy this formula is linked to | +| `config` | object | No | Formula expression configuration | + +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "c4a3b2d1-e5f6-7890-abcd-ef1234567890", + "name": "Carbon Credit Calculator", + "description": "Calculates carbon credits based on emission factors", + "status": "DRAFT", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "policyId": "63e3e5e8a01b3c001234abcd", + "config": {} +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `400 Bad Request` | Malformed request body | +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Missing or invalid formula configuration | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/delete-the-formula-by-its-id.md b/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/delete-the-formula-by-its-id.md index e648e7e78a..fc38011fb3 100644 --- a/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/delete-the-formula-by-its-id.md +++ b/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/delete-the-formula-by-its-id.md @@ -1,5 +1,42 @@ -# Delete the formula by its ID +# Delete the Formula by Its ID -{% swagger src="../../../../../.gitbook/assets/swagger (1).yaml" path="/formulas/{formulaId}" method="delete" %} -[swagger (1).yaml](<../../../../../.gitbook/assets/swagger (1).yaml>) -{% endswagger %} +**`DELETE /api/v1/formulas/{formulaId}`** + +Deletes the formula with the specified ID. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.FORMULAS_FORMULA_CREATE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `formulaId` | string | Yes | Database ID of the formula to delete | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true +``` + +Returns `true` when the formula is successfully deleted. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | `formulaId` parameter is missing or empty | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/export-selected-formulas-into-a-file.md b/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/export-selected-formulas-into-a-file.md index 7ea157b8ad..a10909f3cf 100644 --- a/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/export-selected-formulas-into-a-file.md +++ b/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/export-selected-formulas-into-a-file.md @@ -1,5 +1,41 @@ -# Export selected formulas into a file +# Export Selected Formula into a File -{% swagger src="../../../../../.gitbook/assets/swagger (1).yaml" path="/formulas/{formulaId}/export/file" method="get" %} -[swagger (1).yaml](<../../../../../.gitbook/assets/swagger (1).yaml>) -{% endswagger %} +**`GET /api/v1/formulas/{formulaId}/export/file`** + +Exports a formula and its dependencies as a downloadable ZIP file. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.FORMULAS_FORMULA_READ` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `formulaId` | string | Yes | Database ID of the formula to export | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +Returns a binary ZIP file containing the formula data. + +**Content-Type:** `application/zip` + +**Content-Disposition:** `attachment; filename=theme_` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/loads-import-a-file-and-return-its-preview.md b/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/loads-import-a-file-and-return-its-preview.md index ab4308d149..21f30e9438 100644 --- a/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/loads-import-a-file-and-return-its-preview.md +++ b/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/loads-import-a-file-and-return-its-preview.md @@ -1,5 +1,48 @@ -# Loads (import) a file and return its preview +# Loads (Import) a File and Return Its Preview -{% swagger src="../../../../../.gitbook/assets/swagger (1).yaml" path="/formulas/import/file/preview" method="post" %} -[swagger (1).yaml](<../../../../../.gitbook/assets/swagger (1).yaml>) -{% endswagger %} +**`POST /api/v1/formulas/import/file/preview`** + +Previews a formula ZIP import without persisting any changes to the database. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.FORMULAS_FORMULA_CREATE` + +--- + +## Request + +### Request Body + +Binary ZIP file containing the formula export to preview. + +**Content-Type:** `application/zip` + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "c4a3b2d1-e5f6-7890-abcd-ef1234567890", + "name": "Carbon Credit Calculator", + "description": "Calculates carbon credits based on emission factors", + "status": "DRAFT", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "config": {} +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `400 Bad Request` | Malformed or missing ZIP file | +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/retrieve-the-list-of-all-schemas-and-policies-linked-to-a-formula.md b/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/retrieve-the-list-of-all-schemas-and-policies-linked-to-a-formula.md index 756a384761..fff7c7650c 100644 --- a/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/retrieve-the-list-of-all-schemas-and-policies-linked-to-a-formula.md +++ b/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/retrieve-the-list-of-all-schemas-and-policies-linked-to-a-formula.md @@ -1,5 +1,63 @@ -# Retrieve the list of all schemas and policies linked to a Formula +# Retrieve the List of All Schemas and Policies Linked to a Formula -{% swagger src="../../../../../.gitbook/assets/swagger (1).yaml" path="/formulas/{formulaId}/relationships" method="get" %} -[swagger (1).yaml](<../../../../../.gitbook/assets/swagger (1).yaml>) -{% endswagger %} +**`GET /api/v1/formulas/{formulaId}/relationships`** + +Retrieves the relationship graph for a formula, including all linked policies and schemas. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.FORMULAS_FORMULA_CREATE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `formulaId` | string | Yes | Database ID of the formula | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "c4a3b2d1-e5f6-7890-abcd-ef1234567890", + "policies": [ + { + "id": "63e3e5e8a01b3c001234abce", + "name": "Carbon Offset Policy", + "version": "1.0.0" + } + ], + "schemas": [ + { + "id": "63e3e5e8a01b3c001234abcf", + "name": "Emission Reduction Schema" + } + ] +} +``` + +| Field | Type | Description | +|-------|------|-------------| +| `id` | string | Formula database ID | +| `uuid` | string | Formula UUID | +| `policies` | array | List of policies that reference this formula | +| `schemas` | array | List of schemas that reference this formula | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | `formulaId` parameter is missing or empty | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/return-formula-to-editing-for-the-specified-formula-id.md b/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/return-formula-to-editing-for-the-specified-formula-id.md index 6b7603a3ea..124abb9201 100644 --- a/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/return-formula-to-editing-for-the-specified-formula-id.md +++ b/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/return-formula-to-editing-for-the-specified-formula-id.md @@ -1,54 +1,50 @@ -# Return formula to editing for the specified formula ID +# Return Formula to Editing for the Specified Formula ID -`PUT` `/formulas/{formulaId}/draft` +**`PUT /api/v1/formulas/{formulaId}/draft`** -Return formula to editing for the specified formula ID +Returns a published formula back to draft status, allowing it to be edited again. -**Headers** +**Authentication:** Bearer token required (`Authorization: Bearer `) -| Name | Value | -| ------------- | ------------------ | -| Content-Type | `application/json` | -| Authorization | `Bearer ` | +**Permission:** `Permissions.FORMULAS_FORMULA_CREATE` -**Body** +--- -| Name | Type | Description | -| --------- | ------ | ------------------ | -| formulaId | string | Formula Identifier | +## Request -**Response** +### Path Parameters -{% tabs %} -{% tab title="200" %} -```json5 -description: Successful operation. - content: - application/json: - schema: - $ref: '#/components/schemas/FormulaDTO' -``` -{% endtab %} +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `formulaId` | string | Yes | Database ID of the formula to return to draft | -{% tab title="401" %} -```json5 -description: Unauthorized. -``` -{% endtab %} +--- -{% tab title="403" %} -```json5 -description: Forbidden. -``` -{% endtab %} - -{% tab title="500" %} -```json5 - description: Internal server error. - content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "c4a3b2d1-e5f6-7890-abcd-ef1234567890", + "name": "Carbon Credit Calculator", + "description": "Calculates carbon credits based on emission factors", + "status": "DRAFT", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "policyId": "63e3e5e8a01b3c001234abcd", + "config": {} +} ``` -{% endtab %} -{% endtabs %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Formula with the given ID does not exist | +| `422 Unprocessable Entity` | `formulaId` parameter is missing or empty | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/returns-a-formula-by-its-id.md b/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/returns-a-formula-by-its-id.md index 2a0f2e9c18..8cd011cb1a 100644 --- a/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/returns-a-formula-by-its-id.md +++ b/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/returns-a-formula-by-its-id.md @@ -1,5 +1,49 @@ -# Returns a formula by its ID +# Returns a Formula by Its ID -{% swagger src="../../../../../.gitbook/assets/swagger (1).yaml" path="/formulas/{formulaId}" method="get" %} -[swagger (1).yaml](<../../../../../.gitbook/assets/swagger (1).yaml>) -{% endswagger %} +**`GET /api/v1/formulas/{formulaId}`** + +Retrieves the full configuration of a single formula by its ID. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.FORMULAS_FORMULA_READ` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `formulaId` | string | Yes | Database ID of the formula to retrieve | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "c4a3b2d1-e5f6-7890-abcd-ef1234567890", + "name": "Carbon Credit Calculator", + "description": "Calculates carbon credits based on emission factors", + "status": "PUBLISHED", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "policyId": "63e3e5e8a01b3c001234abcd", + "config": {} +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | `formulaId` parameter is missing or empty | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/returns-a-list-of-formulas.md b/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/returns-a-list-of-formulas.md index 91da80c17e..8b123c293e 100644 --- a/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/returns-a-list-of-formulas.md +++ b/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/returns-a-list-of-formulas.md @@ -1,5 +1,53 @@ -# Returns a list of formulas +# Returns a List of Formulas -{% swagger src="../../../../../.gitbook/assets/swagger (1).yaml" path="/formulas" method="get" %} -[swagger (1).yaml](<../../../../../.gitbook/assets/swagger (1).yaml>) -{% endswagger %} +**`GET /api/v1/formulas`** + +Returns a paginated list of all formulas visible to the authenticated user. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.FORMULAS_FORMULA_READ` + +--- + +## Request + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `pageIndex` | number | No | 0 | Zero-based page index | +| `pageSize` | number | No | 20 | Number of items to return per page | +| `policyId` | string | No | — | Filter formulas by linked policy ID | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +Total item count is returned in the `X-Total-Count` response header. + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "c4a3b2d1-e5f6-7890-abcd-ef1234567890", + "name": "Carbon Credit Calculator", + "description": "Calculates carbon credits based on emission factors", + "status": "PUBLISHED", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "policyId": "63e3e5e8a01b3c001234abcd" + } +] +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/run-formula-without-making-any-persistent-changes-or-executing-transaction..md b/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/run-formula-without-making-any-persistent-changes-or-executing-transaction..md index dabdbd3398..cac997d40b 100644 --- a/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/run-formula-without-making-any-persistent-changes-or-executing-transaction..md +++ b/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/run-formula-without-making-any-persistent-changes-or-executing-transaction..md @@ -1,54 +1,50 @@ -# Run formula without making any persistent changes or executing transaction. +# Run Formula Without Making Any Persistent Changes or Executing Transaction -`PUT` `/formulas/{formulaId}/dry-run` +**`PUT /api/v1/formulas/{formulaId}/dry-run`** -Run formula without making any persistent changes or executing transaction +Runs a formula in dry-run mode without making any persistent changes or executing blockchain transactions. -**Headers** +**Authentication:** Bearer token required (`Authorization: Bearer `) -| Name | Value | -| ------------- | ------------------ | -| Content-Type | `application/json` | -| Authorization | `Bearer ` | +**Permission:** `Permissions.FORMULAS_FORMULA_CREATE` -**Body** +--- -| Name | Type | Description | -| --------- | ------ | ------------------ | -| formulaId | string | Formula Identifier | +## Request -**Response** +### Path Parameters -{% tabs %} -{% tab title="200" %} -```json5 - description: Successful operation. - content: - application/json: - schema: - $ref: '#/components/schemas/FormulaDTO' -``` -{% endtab %} +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `formulaId` | string | Yes | Database ID of the formula to dry-run | -{% tab title="401" %} -```json5 -description: Unauthorized. -``` -{% endtab %} +--- -{% tab title="403" %} -```json5 -description: Forbidden. -``` -{% endtab %} - -{% tab title="500" %} -```json5 -description: Internal server error. - content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "c4a3b2d1-e5f6-7890-abcd-ef1234567890", + "name": "Carbon Credit Calculator", + "description": "Calculates carbon credits based on emission factors", + "status": "DRY-RUN", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "policyId": "63e3e5e8a01b3c001234abcd", + "config": {} +} ``` -{% endtab %} -{% endtabs %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Formula with the given ID does not exist | +| `422 Unprocessable Entity` | `formulaId` parameter is missing or empty | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/update-the-formula-by-its-id.md b/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/update-the-formula-by-its-id.md index e2d80198d4..4f7da6bfae 100644 --- a/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/update-the-formula-by-its-id.md +++ b/docs/guardian/standard-registry/policies/formula-linked-definitions/apis-related-to-formula-linked/update-the-formula-by-its-id.md @@ -1,5 +1,68 @@ -# Update the formula by its ID +# Update the Formula by Its ID -{% swagger src="../../../../../.gitbook/assets/swagger (1).yaml" path="/formulas/{formulaId}" method="put" %} -[swagger (1).yaml](<../../../../../.gitbook/assets/swagger (1).yaml>) -{% endswagger %} +**`PUT /api/v1/formulas/{formulaId}`** + +Updates the configuration of an existing formula for the specified formula ID. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.FORMULAS_FORMULA_CREATE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `formulaId` | string | Yes | Database ID of the formula to update | + +### Request Body + +```json +{ + "name": "Updated Carbon Credit Calculator", + "description": "Updated description", + "policyId": "63e3e5e8a01b3c001234abcd", + "config": {} +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | No | Human-readable formula name | +| `description` | string | No | Description of the formula's purpose | +| `policyId` | string | No | ID of the policy this formula is linked to | +| `config` | object | No | Updated formula expression configuration | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "c4a3b2d1-e5f6-7890-abcd-ef1234567890", + "name": "Updated Carbon Credit Calculator", + "description": "Updated description", + "status": "DRAFT", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "policyId": "63e3e5e8a01b3c001234abcd", + "config": {} +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Formula with the given ID does not exist | +| `422 Unprocessable Entity` | `formulaId` parameter is missing or empty | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/modules/modules-apis/README.md b/docs/guardian/standard-registry/policies/modules/modules-apis/README.md index fb5d9219cf..c06b392a8b 100644 --- a/docs/guardian/standard-registry/policies/modules/modules-apis/README.md +++ b/docs/guardian/standard-registry/policies/modules/modules-apis/README.md @@ -1,2 +1,43 @@ # Modules APIs +Endpoints for creating, managing, importing, exporting, and publishing Guardian policy modules. Modules are reusable policy components that can be shared across policies. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** Standard Registry role required for write operations. + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `GET` | `/api/v1/modules` | Returns all modules | Yes | +| `POST` | `/api/v1/modules` | Creates a new module | Yes | +| `GET` | `/api/v1/modules/{uuid}` | Returns the module configuration | Yes | +| `PUT` | `/api/v1/modules/{uuid}` | Updates the module configuration | Yes | +| `DELETE` | `/api/v1/modules/{uuid}` | Deletes a module | Yes | +| `GET` | `/api/v1/modules/{uuid}/export/file` | Exports a module as a ZIP file | Yes | +| `GET` | `/api/v1/modules/{uuid}/export/message` | Returns the module Hedera message ID | Yes | +| `POST` | `/api/v1/modules/import/file` | Imports a module from a ZIP file | Yes | +| `POST` | `/api/v1/modules/import/message` | Imports a module from an IPFS message ID | Yes | +| `POST` | `/api/v1/modules/import/file/preview` | Previews a module from a ZIP file | Yes | +| `POST` | `/api/v1/modules/import/message/preview` | Previews a module from an IPFS message ID | Yes | +| `PUT` | `/api/v1/modules/{uuid}/publish` | Publishes a module to IPFS | Yes | +| `POST` | `/api/v1/modules/{uuid}/validate` | Validates a module configuration | Yes | +| `GET` | `/api/v1/modules/menu` | Returns the available modules menu | Yes | + +## Endpoints + +- [Returns All Modules](returns-all-modules.md) +- [Creating New Module](creating-new-module.md) +- [Retrieves Module Configuration](retrieves-module-configuration.md) +- [Updates Module Configuration](updates-module-configuration.md) +- [Delete the Module](delete-the-module.md) +- [Exporting Module in ZIP Format](exporting-module-in-zip-format.md) +- [Returns Hedera ID for Specific Module](returns-hedera-id-for-specific-module.md) +- [Import Module from ZIP File](import-module-from-zip-file.md) +- [Import Module from IPFS](import-module-from-ipfs.md) +- [Preview Module from ZIP File](preview-module-from-zip-file.md) +- [Preview Module from IPFS](preview-module-from-ipfs.md) +- [Publishing Module onto IPFS](publishing-module-onto-ipfs.md) +- [Validates Module](validates-module.md) +- [Returns Module Menu](returns-module-menu.md) diff --git a/docs/guardian/standard-registry/policies/modules/modules-differentiation/module-differentiation-apis/README.md b/docs/guardian/standard-registry/policies/modules/modules-differentiation/module-differentiation-apis/README.md index 97beaa96f5..574c596370 100644 --- a/docs/guardian/standard-registry/policies/modules/modules-differentiation/module-differentiation-apis/README.md +++ b/docs/guardian/standard-registry/policies/modules/modules-differentiation/module-differentiation-apis/README.md @@ -1,2 +1,17 @@ # Module Differentiation APIs +Endpoints for comparing two Guardian policy modules and exporting the comparison results. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `POST` | `/api/v1/analytics/compare/modules` | Compares two modules and returns the differences | Yes | +| `GET` | `/api/v1/analytics/compare/modules/export` | Exports module comparison results as a file | Yes | + +## Endpoints + +- [Returns Result of Module Comparison](returns-result-of-module-comparison.md) +- [Exports Comparison Result](exports-comparison-result.md) diff --git a/docs/guardian/standard-registry/policies/policy-creation/creating-a-policy-using-apis/README.md b/docs/guardian/standard-registry/policies/policy-creation/creating-a-policy-using-apis/README.md index ca5d356869..d3369cc745 100644 --- a/docs/guardian/standard-registry/policies/policy-creation/creating-a-policy-using-apis/README.md +++ b/docs/guardian/standard-registry/policies/policy-creation/creating-a-policy-using-apis/README.md @@ -1,2 +1,62 @@ -# Creating a Policy using APIs +# Policy Creation APIs +Endpoints for creating, configuring, publishing, importing, and interacting with Guardian policies. These APIs cover the full policy lifecycle including block data retrieval and group management. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** Standard Registry role required for write operations. + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `GET` | `/api/v1/policies` | Returns all policies for the current user | Yes | +| `POST` | `/api/v1/policies` | Creates a new policy | Yes | +| `GET` | `/api/v1/policies/{policyId}` | Returns a policy configuration | Yes | +| `PUT` | `/api/v1/policies/{policyId}` | Updates a policy configuration | Yes | +| `PUT` | `/api/v1/policies/{policyId}/publish` | Publishes a policy to Hedera | Yes | +| `POST` | `/api/v1/policies/{policyId}/validate` | Validates a policy configuration | Yes | +| `GET` | `/api/v1/policies/{policyId}/export/file` | Exports a policy as a ZIP file | Yes | +| `GET` | `/api/v1/policies/{policyId}/export/message` | Returns the policy Hedera message ID | Yes | +| `POST` | `/api/v1/policies/import/file` | Imports a policy from a ZIP file | Yes | +| `POST` | `/api/v1/policies/import/message` | Imports a policy from an IPFS message ID | Yes | +| `POST` | `/api/v1/policies/import/file-metadata` | Imports a policy from a ZIP file with metadata | Yes | +| `POST` | `/api/v1/policies/import/message/preview` | Previews a policy from an IPFS message ID | Yes | +| `GET` | `/api/v1/policies/{policyId}/blocks` | Returns the root block data for a running policy | Yes | +| `GET` | `/api/v1/policies/{policyId}/blocks/{blockId}` | Returns data for the specified block | Yes | +| `POST` | `/api/v1/policies/{policyId}/blocks/{blockId}` | Sends data to the specified block | Yes | +| `GET` | `/api/v1/policies/{policyId}/tag/{tagName}` | Returns a block ID by its tag name | Yes | +| `GET` | `/api/v1/policies/{policyId}/tag/{tagName}/blocks` | Returns block data by tag | Yes | +| `POST` | `/api/v1/policies/{policyId}/tag/{tagName}/blocks` | Sends data to the block identified by tag | Yes | +| `GET` | `/api/v1/policies/{policyId}/groups` | Returns user groups for the policy | Yes | +| `POST` | `/api/v1/policies/{policyId}/groups` | Makes the selected group active | Yes | +| `GET` | `/api/v1/policies/{policyId}/multiple` | Returns the multi-policy configuration | Yes | +| `POST` | `/api/v1/policies/multiple` | Creates a link between policies | Yes | + +## Endpoints + +- [Prerequisite Steps](prerequesite-steps.md) +- [Policy Listing](policy-listing.md) +- [Creation of a Policy](creation-of-a-policy.md) +- [Retrieves Policy Configuration](retrieves-policy-configuration.md) +- [Updates Policy Configuration](updates-policy-configuration.md) +- [Publish a Policy](publish-a-policy.md) +- [Policy Validation](policy-validation.md) +- [Export to ZIP File](export-to-zip-file.md) +- [Exporting Message ID](exporting-message-id.md) +- [Import from ZIP File](import-from-zip-file.md) +- [Import a Policy](import-a-policy.md) +- [Importing Policy from a ZIP File with Metadata](importing-policy-from-a-zip-file-with-metadata.md) +- [Policy Preview from IPFS](policy-preview-from-ipfs.md) +- [Retrieval of Data from Root Policy Block](retrieval-of-data-from-root-policy-block.md) +- [Request Block Data](request-block-data.md) +- [Sends Data to Specified Block](sends-data-to-specified-block.md) +- [Returns Block ID by Tag](returns-block-id-by-tag.md) +- [Retrieves Block Data by Tag](retrieves-block-data-by-tag.md) +- [Sends Data to Specified Block by Tag](sends-data-to-specified-block-by-tag.md) +- [Sends Data to Specified Block as per Tag](sends-data-to-specified-block-as-per-tag.md) +- [Sends Data to Specified Block Synchronously](sends-data-to-specified-block-synchronously.md) +- [Returns List of Groups of a Particular User](returns-list-of-groups-of-a-particular-user.md) +- [Make the Selected Group Active](make-the-selected-group-active.md) +- [Requesting Multi-Policy Config](requesting-multi-policy-config.md) +- [Creating Link Between Policies](creating-link-between-policies.md) diff --git a/docs/guardian/standard-registry/policies/policy-differentiation/policy-differentiation-apis/README.md b/docs/guardian/standard-registry/policies/policy-differentiation/policy-differentiation-apis/README.md index 6f82a6365f..bb0797ca47 100644 --- a/docs/guardian/standard-registry/policies/policy-differentiation/policy-differentiation-apis/README.md +++ b/docs/guardian/standard-registry/policies/policy-differentiation/policy-differentiation-apis/README.md @@ -1,2 +1,19 @@ -# Policy Compare and Search APIs +# Policy Differentiation APIs +Endpoints for comparing two Guardian policies and exporting the comparison results. Used for audit and review of policy version differences. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `POST` | `/api/v1/analytics/compare/policies` | Compares two policies and returns the differences | Yes | +| `POST` | `/api/v1/analytics/search/policies` | Searches for similar policies | Yes | +| `GET` | `/api/v1/analytics/compare/policies/export` | Exports policy comparison results as a file | Yes | + +## Endpoints + +- [Returns Result of Policy Comparison](returns-result-of-policy-comparison.md) +- [Searching Policies](searching-policies.md) +- [Exports Comparison Results](exports-comparison-results.md) diff --git a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/create-a-new-label-document-for-token-vp.md b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/create-a-new-label-document-for-token-vp.md index bc43cfb832..e5de8c58e2 100644 --- a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/create-a-new-label-document-for-token-vp.md +++ b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/create-a-new-label-document-for-token-vp.md @@ -1,5 +1,64 @@ -# Create a new Label document for token (VP) +# Create a New Label Document for Token (VP) -{% swagger src="../../../../../.gitbook/assets/swagger (1) (1) (1).yaml" path="/policy-labels/{definitionId}/documents" method="post" %} -[swagger (1) (1) (1).yaml](<../../../../../.gitbook/assets/swagger (1) (1) (1).yaml>) -{% endswagger %} +**`POST /api/v1/policy-labels/{definitionId}/documents`** + +Creates a new label document certifying a VP token document against the specified label definition. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.STATISTICS_LABEL_CREATE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `definitionId` | string | Yes | Policy label definition identifier | + +### Request Body + +```json +{ + "tokenId": "63e3e5e8a01b3c001234abcd", + "document": {}, + "relationships": [] +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `tokenId` | string | Yes | ID of the VP document being labeled | +| `document` | object | Yes | Label document content | +| `relationships` | array | No | Array of related document IDs | + +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "definitionId": "63e3e5e8a01b3c001234abce", + "tokenId": "63e3e5e8a01b3c001234abcf", + "status": "NEW", + "document": {}, + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001" +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `400 Bad Request` | Malformed request body | +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | `definitionId` is missing, or document configuration is invalid | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/creating-new-label-definition.md b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/creating-new-label-definition.md index e7c645d8a0..cac2cc30bd 100644 --- a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/creating-new-label-definition.md +++ b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/creating-new-label-definition.md @@ -1,5 +1,61 @@ -# Creating new Label definition +# Creating New Label Definition -{% swagger src="../../../../../.gitbook/assets/swagger (1) (1) (1).yaml" path="/policy-labels" method="post" %} -[swagger (1) (1) (1).yaml](<../../../../../.gitbook/assets/swagger (1) (1) (1).yaml>) -{% endswagger %} +**`POST /api/v1/policy-labels`** + +Creates a new policy label definition. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.STATISTICS_LABEL_CREATE` + +--- + +## Request + +### Request Body + +```json +{ + "name": "Carbon Credit Label", + "description": "Certification label for verified carbon credits", + "policyId": "63e3e5e8a01b3c001234abcd", + "config": {} +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | Yes | Human-readable name for the label definition | +| `description` | string | No | Description of what this label certifies | +| `policyId` | string | Yes | ID of the policy this label applies to | +| `config` | object | Yes | Label configuration object | + +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "name": "Carbon Credit Label", + "description": "Certification label for verified carbon credits", + "policyId": "63e3e5e8a01b3c001234abcd", + "status": "DRAFT", + "config": {}, + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001" +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `400 Bad Request` | Malformed request body | +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Invalid label configuration | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/delete-label-definition-by-id.md b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/delete-label-definition-by-id.md index a8825e1d1a..02c68858dd 100644 --- a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/delete-label-definition-by-id.md +++ b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/delete-label-definition-by-id.md @@ -1,5 +1,40 @@ -# Delete Label definition by ID +# Delete Label Definition by ID -{% swagger src="../../../../../.gitbook/assets/swagger (1) (1) (1).yaml" path="/policy-labels/{definitionId}" method="delete" %} -[swagger (1) (1) (1).yaml](<../../../../../.gitbook/assets/swagger (1) (1) (1).yaml>) -{% endswagger %} +**`DELETE /api/v1/policy-labels/{definitionId}`** + +Deletes the policy label definition with the specified ID. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.STATISTICS_LABEL_CREATE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `definitionId` | string | Yes | Policy label definition identifier | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | `definitionId` is missing or invalid | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/export-label-configuration-to-a-file.md b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/export-label-configuration-to-a-file.md index 226a3a5291..1306dd9eee 100644 --- a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/export-label-configuration-to-a-file.md +++ b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/export-label-configuration-to-a-file.md @@ -1,5 +1,43 @@ -# Export Label configuration to a file +# Export Label Configuration to a File -{% swagger src="../../../../../.gitbook/assets/swagger (1) (1) (1).yaml" path="/policy-statistics/{definitionId}/export/file" method="get" %} -[swagger (1) (1) (1).yaml](<../../../../../.gitbook/assets/swagger (1) (1) (1).yaml>) -{% endswagger %} +**`GET /api/v1/policy-labels/{definitionId}/export/file`** + +Returns a zip file containing the policy label definition configuration for the specified label ID. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.STATISTICS_LABEL_READ` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `definitionId` | string | Yes | Policy label definition identifier | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +Returns a binary zip file as an attachment. + +| Header | Value | +|--------|-------| +| `Content-Type` | `application/zip` | +| `Content-Disposition` | `attachment; filename=theme_` | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | `definitionId` is missing or invalid | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/import-label-configuration-from-a-file.md b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/import-label-configuration-from-a-file.md index 05020c143e..b4eef712f3 100644 --- a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/import-label-configuration-from-a-file.md +++ b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/import-label-configuration-from-a-file.md @@ -1,5 +1,59 @@ -# Import Label configuration from a file +# Import Label Configuration from a File -{% swagger src="../../../../../.gitbook/assets/swagger (1) (1) (1).yaml" path="/policy-statistics/{policyId}/import/file" method="post" %} -[swagger (1) (1) (1).yaml](<../../../../../.gitbook/assets/swagger (1) (1) (1).yaml>) -{% endswagger %} +**`POST /api/v1/policy-labels/{policyId}/import/file`** + +Imports new policy label definitions from a zip file into the local database. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.STATISTICS_LABEL_CREATE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `policyId` | string | Yes | Policy identifier to associate the imported labels with | + +### Request Body + +Binary zip file containing the label definitions to import. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| *(binary)* | file | Yes | A `.zip` file exported from a Guardian instance | + +> Set `Content-Type: application/zip` when uploading the file. + +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "name": "Carbon Credit Label", + "description": "Certification label for verified carbon credits", + "policyId": "63e3e5e8a01b3c001234abcd", + "status": "DRAFT", + "config": {}, + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001" +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `400 Bad Request` | Malformed or unreadable zip file | +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | `policyId` is missing or the file content is invalid | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/preview-of-the-imported-file.md b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/preview-of-the-imported-file.md index 5993132823..8a6a545dbb 100644 --- a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/preview-of-the-imported-file.md +++ b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/preview-of-the-imported-file.md @@ -1,5 +1,51 @@ -# Preview of the imported file +# Preview of the Imported File -{% swagger src="../../../../../.gitbook/assets/swagger (1) (1) (1).yaml" path="/policy-statistics/import/file/preview" method="post" %} -[swagger (1) (1) (1).yaml](<../../../../../.gitbook/assets/swagger (1) (1) (1).yaml>) -{% endswagger %} +**`POST /api/v1/policy-labels/import/file/preview`** + +Returns a preview of the policy label definition contained in a zip file without importing it. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.STATISTICS_LABEL_CREATE` + +--- + +## Request + +### Request Body + +Binary zip file to preview. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| *(binary)* | file | Yes | A `.zip` file exported from a Guardian instance | + +> Set `Content-Type: application/zip` when uploading the file. + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "name": "Carbon Credit Label", + "description": "Certification label for verified carbon credits", + "policyId": "63e3e5e8a01b3c001234abcd", + "status": "DRAFT", + "config": {} +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `400 Bad Request` | Malformed or unreadable zip file | +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/publish-label-definition-by-id-asynchronously.md b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/publish-label-definition-by-id-asynchronously.md index b15ae19ccb..1e3227593e 100644 --- a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/publish-label-definition-by-id-asynchronously.md +++ b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/publish-label-definition-by-id-asynchronously.md @@ -1,5 +1,46 @@ -# Publish Label definition by ID asynchronously +# Publish Label Definition by ID Asynchronously -{% swagger src="../../../../../.gitbook/assets/swagger (1) (1) (1).yaml" path="/policy-labels/push/{definitionId}/publish" method="put" %} -[swagger (1) (1) (1).yaml](<../../../../../.gitbook/assets/swagger (1) (1) (1).yaml>) -{% endswagger %} +**`PUT /api/v1/policy-labels/push/{definitionId}/publish`** + +Asynchronously publishes the policy label definition with the specified ID. Returns a task immediately; poll for completion. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.STATISTICS_LABEL_CREATE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `definitionId` | string | Yes | Policy label definition identifier | + +--- + +## Response + +### Success Response + +**Status:** `202 Accepted` + +```json +{ + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Publish policy label" +} +``` + +Poll `GET /tasks/{taskId}` to retrieve the result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Label definition with the specified ID does not exist | +| `422 Unprocessable Entity` | `definitionId` is missing or invalid | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/publish-label-definition-by-id.md b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/publish-label-definition-by-id.md index b15fc31e4d..69631b42e9 100644 --- a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/publish-label-definition-by-id.md +++ b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/publish-label-definition-by-id.md @@ -1,5 +1,49 @@ -# Publish Label definition by ID +# Publish Label Definition by ID -{% swagger src="../../../../../.gitbook/assets/swagger (1) (1) (1).yaml" path="/policy-labels/{definitionId}/publish" method="put" %} -[swagger (1) (1) (1).yaml](<../../../../../.gitbook/assets/swagger (1) (1) (1).yaml>) -{% endswagger %} +**`PUT /api/v1/policy-labels/{definitionId}/publish`** + +Publishes the policy label definition with the specified ID, making it active and immutable. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.STATISTICS_LABEL_CREATE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `definitionId` | string | Yes | Policy label definition identifier | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "name": "Carbon Credit Label", + "description": "Certification label for verified carbon credits", + "policyId": "63e3e5e8a01b3c001234abcd", + "status": "PUBLISHED", + "config": {}, + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001" +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Label definition with the specified ID does not exist | +| `422 Unprocessable Entity` | `definitionId` is missing or invalid | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-a-label-definition-configuration-by-id.md b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-a-label-definition-configuration-by-id.md index 867faca25c..4d6251b535 100644 --- a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-a-label-definition-configuration-by-id.md +++ b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-a-label-definition-configuration-by-id.md @@ -1,5 +1,49 @@ -# Retrieve a label definition configuration by ID +# Retrieve a Label Definition Configuration by ID -{% swagger src="../../../../../.gitbook/assets/swagger (1) (1) (1).yaml" path="/policy-labels/{definitionId}" method="get" %} -[swagger (1) (1) (1).yaml](<../../../../../.gitbook/assets/swagger (1) (1) (1).yaml>) -{% endswagger %} +**`GET /api/v1/policy-labels/{definitionId}`** + +Retrieves the policy label definition for the specified ID. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.STATISTICS_LABEL_READ` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `definitionId` | string | Yes | Policy label definition identifier | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "name": "Carbon Credit Label", + "description": "Certification label for verified carbon credits", + "policyId": "63e3e5e8a01b3c001234abcd", + "status": "DRAFT", + "config": {}, + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001" +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Label definition with the specified ID does not exist | +| `422 Unprocessable Entity` | `definitionId` is missing or invalid | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-a-list-of-created-label-documents.md b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-a-list-of-created-label-documents.md index f2737eea86..9fb2bd8120 100644 --- a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-a-list-of-created-label-documents.md +++ b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-a-list-of-created-label-documents.md @@ -1,5 +1,62 @@ -# Retrieve a list of created Label documents +# Retrieve a List of Created Label Documents -{% swagger src="../../../../../.gitbook/assets/swagger (1) (1) (1).yaml" path="/policy-labels/{definitionId}/documents" method="get" %} -[swagger (1) (1) (1).yaml](<../../../../../.gitbook/assets/swagger (1) (1) (1).yaml>) -{% endswagger %} +**`GET /api/v1/policy-labels/{definitionId}/documents`** + +Returns a paginated list of all label documents created under the specified label definition. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.STATISTICS_LABEL_READ` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `definitionId` | string | Yes | Policy label definition identifier | + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `pageIndex` | number | No | 0 | Zero-based page index | +| `pageSize` | number | No | 20 | Number of items to return per page | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +Returns an array of label document objects. The total count is provided in the `X-Total-Count` response header. + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "definitionId": "63e3e5e8a01b3c001234abce", + "tokenId": "63e3e5e8a01b3c001234abcf", + "status": "NEW", + "document": {}, + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001" + } +] +``` + +| Header | Description | +|--------|-------------| +| `X-Total-Count` | Total number of label documents matching the query | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | `definitionId` is missing or invalid | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-label-document-by-id.md b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-label-document-by-id.md index caaa62900e..2a091a78cb 100644 --- a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-label-document-by-id.md +++ b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-label-document-by-id.md @@ -1,5 +1,49 @@ -# Retrieve Label document by ID +# Retrieve Label Document by ID -{% swagger src="../../../../../.gitbook/assets/swagger (1) (1) (1).yaml" path="/policy-labels/{definitionId}/documents/{documentId}" method="get" %} -[swagger (1) (1) (1).yaml](<../../../../../.gitbook/assets/swagger (1) (1) (1).yaml>) -{% endswagger %} +**`GET /api/v1/policy-labels/{definitionId}/documents/{documentId}`** + +Retrieves a specific label document by its ID within the specified label definition. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.STATISTICS_LABEL_READ` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `definitionId` | string | Yes | Policy label definition identifier | +| `documentId` | string | Yes | Label document identifier | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "definitionId": "63e3e5e8a01b3c001234abce", + "tokenId": "63e3e5e8a01b3c001234abcf", + "status": "NEW", + "document": {}, + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001" +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Label document with the specified ID does not exist | +| `422 Unprocessable Entity` | `definitionId` or `documentId` is missing or invalid | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-linked-label-documents-by-id.md b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-linked-label-documents-by-id.md index 2efbe8a4fd..c2172828de 100644 --- a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-linked-label-documents-by-id.md +++ b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-linked-label-documents-by-id.md @@ -1,5 +1,55 @@ -# Retrieve linked Label documents by ID +# Retrieve Linked Label Documents by ID -{% swagger src="../../../../../.gitbook/assets/swagger (1) (1) (1).yaml" path="/policy-labels/{definitionId}/documents/{documentId}/relationships" method="get" %} -[swagger (1) (1) (1).yaml](<../../../../../.gitbook/assets/swagger (1) (1) (1).yaml>) -{% endswagger %} +**`GET /api/v1/policy-labels/{definitionId}/documents/{documentId}/relationships`** + +Retrieves the relationship graph for a label document, including all linked documents and their dependencies. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.STATISTICS_STATISTIC_READ` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `definitionId` | string | Yes | Policy label definition identifier | +| `documentId` | string | Yes | Label document identifier | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "document": { + "id": "63e3e5e8a01b3c001234abcd", + "definitionId": "63e3e5e8a01b3c001234abce", + "status": "NEW" + }, + "relationships": [ + { + "id": "63e3e5e8a01b3c001234abcf", + "type": "VerifiableCredential", + "document": {} + } + ] +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | `definitionId` or `documentId` is missing or invalid | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-the-list-of-components-for-label-configuration-schemas-policies-etc.md b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-the-list-of-components-for-label-configuration-schemas-policies-etc.md index cf14a26092..f0be2a10a7 100644 --- a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-the-list-of-components-for-label-configuration-schemas-policies-etc.md +++ b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-the-list-of-components-for-label-configuration-schemas-policies-etc.md @@ -1,5 +1,48 @@ -# Retrieve the list of components for Label configuration (schemas, policies, etc) +# Retrieve the List of Components for Label Configuration (Schemas, Policies, etc.) -{% swagger src="../../../../../.gitbook/assets/swagger (1) (1) (1).yaml" path="/policy-labels/{definitionId}/relationships" method="get" %} -[swagger (1) (1) (1).yaml](<../../../../../.gitbook/assets/swagger (1) (1) (1).yaml>) -{% endswagger %} +**`GET /api/v1/policy-labels/{definitionId}/relationships`** + +Retrieves policy label relationships, including referenced schemas, policies, and other components for the specified label definition. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.STATISTICS_LABEL_READ` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `definitionId` | string | Yes | Policy label definition identifier | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "label": { + "id": "63e3e5e8a01b3c001234abcd", + "name": "Carbon Credit Label" + }, + "schemas": [], + "policies": [] +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | `definitionId` is missing or invalid | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-the-list-of-created-tokens-vps-for-which-a-label-document-can-be-created.md b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-the-list-of-created-tokens-vps-for-which-a-label-document-can-be-created.md index c039bf19e0..f399f93167 100644 --- a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-the-list-of-created-tokens-vps-for-which-a-label-document-can-be-created.md +++ b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-the-list-of-created-tokens-vps-for-which-a-label-document-can-be-created.md @@ -1,5 +1,61 @@ -# Retrieve the list of created tokens (VPs) for which a Label document can be created +# Retrieve the List of Created Tokens (VPs) for Which a Label Document Can Be Created -{% swagger src="../../../../../.gitbook/assets/swagger (1) (1) (1).yaml" path="/policy-labels/{definitionId}/tokens" method="get" %} -[swagger (1) (1) (1).yaml](<../../../../../.gitbook/assets/swagger (1) (1) (1).yaml>) -{% endswagger %} +**`GET /api/v1/policy-labels/{definitionId}/tokens`** + +Returns a paginated list of VP (Verifiable Presentation) documents associated with the label definition for which label documents can be created. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.STATISTICS_LABEL_READ` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `definitionId` | string | Yes | Policy label definition identifier | + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `pageIndex` | number | No | 0 | Zero-based page index | +| `pageSize` | number | No | 20 | Number of items to return per page | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +Returns an array of VC document objects. The total count is provided in the `X-Total-Count` response header. + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "type": "VerifiableCredential", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "schema": "63e3e5e8a01b3c001234abce", + "document": {} + } +] +``` + +| Header | Description | +|--------|-------------| +| `X-Total-Count` | Total number of VP documents matching the query | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | `definitionId` is missing or invalid | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-the-list-of-label-definitions.md b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-the-list-of-label-definitions.md index 050d91937b..75bd70b2c9 100644 --- a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-the-list-of-label-definitions.md +++ b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-the-list-of-label-definitions.md @@ -1,5 +1,56 @@ -# Retrieve the list of Label definitions +# Retrieve the List of Label Definitions -{% swagger src="../../../../../.gitbook/assets/swagger (1) (1) (1).yaml" path="/policy-labels" method="get" %} -[swagger (1) (1) (1).yaml](<../../../../../.gitbook/assets/swagger (1) (1) (1).yaml>) -{% endswagger %} +**`GET /api/v1/policy-labels`** + +Returns a paginated list of all policy label definitions owned by the authenticated user. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.STATISTICS_LABEL_READ` + +--- + +## Request + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `pageIndex` | number | No | 0 | Zero-based page index | +| `pageSize` | number | No | 20 | Number of items to return per page | +| `policyInstanceTopicId` | string | No | — | Filter by policy instance topic ID (e.g. `0.0.4532001`) | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +Returns an array of policy label definition objects. The total count is provided in the `X-Total-Count` response header. + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "name": "Carbon Credit Label", + "description": "Certification label for verified carbon credits", + "policyId": "63e3e5e8a01b3c001234abcd", + "status": "DRAFT", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001" + } +] +``` + +| Header | Description | +|--------|-------------| +| `X-Total-Count` | Total number of label definitions matching the query | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-token-vp-and-all-its-dependencies-by-document-id.md b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-token-vp-and-all-its-dependencies-by-document-id.md index 80648ba537..e8a03cfc10 100644 --- a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-token-vp-and-all-its-dependencies-by-document-id.md +++ b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/retrieve-token-vp-and-all-its-dependencies-by-document-id.md @@ -1,5 +1,49 @@ -# Retrieve token (VP) and all its dependencies by document ID +# Retrieve Token (VP) and All Its Dependencies by Document ID -{% swagger src="../../../../../.gitbook/assets/swagger (1) (1) (1).yaml" path="/policy-labels/{definitionId}/tokens/{documentId}" method="get" %} -[swagger (1) (1) (1).yaml](<../../../../../.gitbook/assets/swagger (1) (1) (1).yaml>) -{% endswagger %} +**`GET /api/v1/policy-labels/{definitionId}/tokens/{documentId}`** + +Returns the VP document and all its related dependency documents for a given label definition and document ID. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.STATISTICS_LABEL_READ` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `definitionId` | string | Yes | Policy label definition identifier | +| `documentId` | string | Yes | VP document identifier | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "type": "VerifiableCredential", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "schema": "63e3e5e8a01b3c001234abce", + "document": {} + } +] +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | `definitionId` or `documentId` is missing or invalid | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/search-for-labels-and-statistics-for-importing-into-label-configuration.md b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/search-for-labels-and-statistics-for-importing-into-label-configuration.md index 55a4d9c368..f0a8a4604e 100644 --- a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/search-for-labels-and-statistics-for-importing-into-label-configuration.md +++ b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/search-for-labels-and-statistics-for-importing-into-label-configuration.md @@ -1,5 +1,62 @@ -# Search for Labels and Statistics for importing into Label configuration +# Search for Labels and Statistics for Importing into Label Configuration -{% swagger src="../../../../../.gitbook/assets/swagger (1) (1) (1).yaml" path="/policy-labels/components" method="post" %} -[swagger (1) (1) (1).yaml](<../../../../../.gitbook/assets/swagger (1) (1) (1).yaml>) -{% endswagger %} +**`POST /api/v1/policy-labels/components`** + +Returns a list of available labels and statistics components that can be imported into a label configuration. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.STATISTICS_LABEL_CREATE` + +--- + +## Request + +### Request Body + +```json +{ + "policyId": "63e3e5e8a01b3c001234abcd", + "policyInstanceTopicId": "0.0.4532001" +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `policyId` | string | No | Filter by policy ID | +| `policyInstanceTopicId` | string | No | Filter by policy instance topic ID | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "labels": [ + { + "id": "63e3e5e8a01b3c001234abcd", + "name": "Carbon Credit Label", + "status": "PUBLISHED" + } + ], + "statistics": [ + { + "id": "63e3e5e8a01b3c001234abce", + "name": "Emissions Statistic", + "status": "PUBLISHED" + } + ] +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/update-label-configuration-by-id.md b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/update-label-configuration-by-id.md index 94129cd9b8..364f99f105 100644 --- a/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/update-label-configuration-by-id.md +++ b/docs/guardian/standard-registry/policies/policy-labels/apis-related-to-policy-labels/update-label-configuration-by-id.md @@ -1,7 +1,68 @@ -# Update Label configuration by ID +# Update Label Configuration by ID +**`PUT /api/v1/policy-labels/{definitionId}`** +Updates the policy label definition configuration for the specified label ID. -{% swagger src="../../../../../.gitbook/assets/swagger (1) (1) (1).yaml" path="/policy-labels/{definitionId}" method="put" %} -[swagger (1) (1) (1).yaml](<../../../../../.gitbook/assets/swagger (1) (1) (1).yaml>) -{% endswagger %} +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.STATISTICS_LABEL_CREATE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `definitionId` | string | Yes | Policy label definition identifier | + +### Request Body + +```json +{ + "name": "Updated Carbon Credit Label", + "description": "Updated certification label for verified carbon credits", + "policyId": "63e3e5e8a01b3c001234abcd", + "config": {} +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | Yes | Human-readable name for the label definition | +| `description` | string | No | Description of what this label certifies | +| `policyId` | string | Yes | ID of the policy this label applies to | +| `config` | object | Yes | Updated label configuration object | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "name": "Updated Carbon Credit Label", + "description": "Updated certification label for verified carbon credits", + "policyId": "63e3e5e8a01b3c001234abcd", + "status": "DRAFT", + "config": {}, + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001" +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `400 Bad Request` | Malformed request body | +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Label definition with the specified ID does not exist | +| `422 Unprocessable Entity` | `definitionId` is missing or invalid | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/policy-wizard/policy-wizard-apis/README.md b/docs/guardian/standard-registry/policies/policy-wizard/policy-wizard-apis/README.md index 0bde6b360a..042588f0a5 100644 --- a/docs/guardian/standard-registry/policies/policy-wizard/policy-wizard-apis/README.md +++ b/docs/guardian/standard-registry/policies/policy-wizard/policy-wizard-apis/README.md @@ -1,2 +1,19 @@ # Policy Wizard APIs +Endpoints for creating and previewing Guardian policies using the guided policy wizard workflow. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** Standard Registry role required. + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `POST` | `/api/v1/wizard/policy` | Creates a new policy using the wizard configuration | Yes | +| `GET` | `/api/v1/wizard/{policyId}/config` | Returns the wizard configuration for an existing policy | Yes | + +## Endpoints + +- [Creating New Policy](creating-new-policy.md) +- [Getting Policy Configuration](getting-policy-configuration.md) diff --git a/docs/guardian/standard-registry/policies/policy-wizard/policy-wizard-apis/creating-new-policy.md b/docs/guardian/standard-registry/policies/policy-wizard/policy-wizard-apis/creating-new-policy.md index 30c7e2095d..2747c6b01a 100644 --- a/docs/guardian/standard-registry/policies/policy-wizard/policy-wizard-apis/creating-new-policy.md +++ b/docs/guardian/standard-registry/policies/policy-wizard/policy-wizard-apis/creating-new-policy.md @@ -1,186 +1,116 @@ -# Creating new Policy - -{% swagger method="post" path="" baseUrl="/policy" summary="Creates a new policy." %} -{% swagger-description %} -Creates a new policy by wizard. Only users with the Standard Registry role are allowed to make the request. security: -{% endswagger-description %} - -{% swagger-parameter in="body" type="Object" required="true" %} -Object that contains wizard configuration. -{% endswagger-parameter %} - -{% swagger-response status="201: Created" description="Successful Operation" %} -``` -content: - application/json: - schema: - type: object - properties: - policyId: - type: string - wizardConfig: - $ref: "#/components/schemas/WizardConfig" +# Creating a New Policy via Wizard + +**`POST /api/v1/wizard/policy`** + +Creates a new policy using the wizard configuration. Only Standard Registry users are allowed to make this request. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.POLICIES_POLICY_CREATE` + +--- + +## Request + +### Request Body + +```json +{ + "wizardConfig": { + "policy": { + "name": "Example Policy", + "description": "Policy description", + "topicDescription": "Topic description", + "policyTag": "ExampleTag" + }, + "roles": ["OWNER"], + "schemas": [ + { + "name": "Example Schema", + "iri": "#ExampleSchema", + "isApproveEnable": false, + "isMintSchema": false, + "mintOptions": {}, + "dependencySchemaIri": null, + "relationshipsSchemaIri": null, + "initialRolesFor": [], + "rolesConfig": [ + { + "role": "OWNER", + "isApprover": true, + "isCreator": true, + "fields": [], + "gridColumns": [] + } + ] + } + ], + "trustChain": [ + { + "role": "OWNER", + "mintSchemaIri": "#ExampleSchema", + "viewOnlyOwnDocuments": true + } + ] + } +} ``` -{% endswagger-response %} - -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} - -{% endswagger-response %} - -{% swagger-response status="403: Forbidden" description="Forbidden" %} - -{% endswagger-response %} - -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: "#/components/schemas/Error" -``` -{% endswagger-response %} -{% endswagger %} - -{% swagger method="post" path="" baseUrl="/policy/push" summary="Creates a new policy. - Deprecated" %} -{% swagger-description %} -Creates a new policy by wizard. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} - -{% swagger-parameter in="body" type="Object" required="true" %} -Object that contains wizard configuration. -{% endswagger-parameter %} -{% swagger-response status="201: Created" description="Successful Operation" %} -``` -content: - application/json: - schema: - $ref: "#/components/schemas/Task" -``` -{% endswagger-response %} +| Field | Type | Required | Description | +|-----------------------------|---------|----------|------------------------------------------------------| +| `wizardConfig` | object | Yes | Wizard configuration object | +| `wizardConfig.policy` | object | Yes | Policy metadata (name, description, tag, etc.) | +| `wizardConfig.roles` | array | No | List of roles in the policy | +| `wizardConfig.schemas` | array | No | Schema configurations to include | +| `wizardConfig.trustChain` | array | No | Trust chain configuration per role | -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +--- -{% endswagger-response %} +## Response -{% swagger-response status="403: Forbidden" description="Forbidden" %} +### Success Response -{% endswagger-response %} +**Status:** `201 Created` -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} +```json +{ + "policyId": "63e3e5e8a01b3c001234abcd", + "wizardConfig": {} +} ``` -content: - application/json: - schema: - $ref: "#/components/schemas/Error" -``` -{% endswagger-response %} -{% endswagger %} - -{% swagger method="post" path="" baseUrl="/wizard/push/policy" summary="Creates a new policy" %} -{% swagger-description %} -Creates a new policy by wizard. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} - -{% swagger-parameter in="body" name="saveState" type="Boolean" required="true" %} - -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="policy name" type="String" required="true" %} - -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="policy description" type="String" required="true" %} - -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="topicDescription" type="String" required="true" %} - -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="policyTag" type="String" required="true" %} -{% endswagger-parameter %} +| Field | Type | Description | +|----------------|--------|-------------------------------------------| +| `policyId` | string | The ID of the newly created policy | +| `wizardConfig` | object | The wizard configuration that was applied | -{% swagger-parameter in="body" name="schemas name" type="String" required="true" %} +### Error Responses -{% endswagger-parameter %} +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | -{% swagger-parameter in="body" name="iri" type="String" required="true" %} +--- -{% endswagger-parameter %} +## Async Variant -{% swagger-parameter in="body" name="isApproveEnable" type="Boolean" required="true" %} +**`POST /api/v1/wizard/push/policy`** -{% endswagger-parameter %} +Asynchronous version of policy creation via wizard. Returns immediately with a task identifier. -{% swagger-parameter in="body" name="isMintSchema" type="Boolean" required="true" %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% endswagger-parameter %} +**Permission:** `Permissions.POLICIES_POLICY_CREATE` -{% swagger-parameter in="body" name="mintOptions" type="Object" required="true" %} +**Status:** `202 Accepted` -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="dependencySchemaIri" type="String" required="true" %} - -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="relationshipsSchemaIri" type="String" required="true" %} - -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="initialRolesFor" type="String" required="true" %} - -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="role" type="String" required="true" %} - -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="isApprover" type="Boolean" required="true" %} - -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="isCreator" type="Boolean" required="true" %} - -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="field" type="String" required="true" %} - -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="title" type="String" required="true" %} - -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="role" type="String" required="true" %} - -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="mintSchemaIri" type="String" required="true" %} - -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="viewOnlyOwnDocuments" type="Boolean" required="true" %} - -{% endswagger-parameter %} - -{% swagger-response status="200: OK" description="Successful Operation" %} +```json +{ + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Create policy" +} ``` - content: - application/json: - schema: - type: boolean -``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' -``` -{% endswagger-response %} -{% endswagger %} +Poll `GET /tasks/{taskId}` to retrieve the result. diff --git a/docs/guardian/standard-registry/policies/policy-wizard/policy-wizard-apis/getting-policy-configuration.md b/docs/guardian/standard-registry/policies/policy-wizard/policy-wizard-apis/getting-policy-configuration.md index cdf47c5be6..5c89ca0826 100644 --- a/docs/guardian/standard-registry/policies/policy-wizard/policy-wizard-apis/getting-policy-configuration.md +++ b/docs/guardian/standard-registry/policies/policy-wizard/policy-wizard-apis/getting-policy-configuration.md @@ -1,46 +1,75 @@ # Getting Policy Configuration -{% swagger method="post" path="" baseUrl="/{policyId}/config" summary="Get policy config." %} -{% swagger-description %} -Get policy config by wizard. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /api/v1/wizard/{policyId}/config`** -{% swagger-parameter in="path" name="policyId" type="String" required="true" %} -Policy identifier. -{% endswagger-parameter %} +Retrieves a policy configuration preview using the wizard settings for the specified policy. Only Standard Registry users are allowed to make this request. -{% swagger-parameter in="body" type="Object" required="true" %} -Object that contains wizard configuration. -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - type: object - properties: - policyConfig: - $ref: "#/components/schemas/PolicyConfig" - wizardConfig: - $ref: "#/components/schemas/WizardConfig" -``` -{% endswagger-response %} +**Permission:** `Permissions.POLICIES_POLICY_CREATE` + +--- -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +## Request -{% endswagger-response %} +### Path Parameters -{% swagger-response status="403: Forbidden" description="Forbidden" %} +| Parameter | Type | Required | Description | +|------------|--------|----------|---------------------------------| +| `policyId` | string | Yes | The ID of the policy to preview | -{% endswagger-response %} +### Request Body -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} +```json +{ + "wizardConfig": { + "policy": { + "name": "Example Policy", + "description": "Policy description", + "topicDescription": "Topic description", + "policyTag": "ExampleTag" + }, + "roles": ["OWNER"], + "schemas": [], + "trustChain": [] + } +} ``` -content: - application/json: - schema: - $ref: "#/components/schemas/Error" + +| Field | Type | Required | Description | +|----------------|--------|----------|---------------------------------------| +| `wizardConfig` | object | Yes | Wizard configuration object to preview | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "policyConfig": { + "id": "63e3e5e8a01b3c001234abcd", + "name": "Example Policy", + "version": "1.0.0", + "config": {} + }, + "wizardConfig": {} +} ``` -{% endswagger-response %} -{% endswagger %} + +| Field | Type | Description | +|----------------|--------|--------------------------------------------------| +| `policyConfig` | object | The resulting policy configuration object | +| `wizardConfig` | object | The wizard configuration used to generate it | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Policy not found | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/record-replay/record-replay-apis/README.md b/docs/guardian/standard-registry/policies/record-replay/record-replay-apis/README.md index 97ab126a5a..2311e3a550 100644 --- a/docs/guardian/standard-registry/policies/record-replay/record-replay-apis/README.md +++ b/docs/guardian/standard-registry/policies/record-replay/record-replay-apis/README.md @@ -1,2 +1,37 @@ -# Record/Replay APIs +# Record and Replay APIs +Endpoints for recording, replaying, and managing Guardian policy execution sessions. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** Standard Registry role required. + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `POST` | `/api/v1/record/{policyId}/recording/start` | Starts recording a policy execution session | Yes | +| `POST` | `/api/v1/record/{policyId}/recording/stop` | Stops the current recording | Yes | +| `GET` | `/api/v1/record/{policyId}/recording/actions` | Returns all recorded actions | Yes | +| `GET` | `/api/v1/record/{policyId}` | Returns the current recording status | Yes | +| `POST` | `/api/v1/record/{policyId}/run/start` | Starts replaying a recording from a ZIP file | Yes | +| `POST` | `/api/v1/record/{policyId}/run/stop` | Stops the replay | Yes | +| `GET` | `/api/v1/record/{policyId}/run/results` | Returns the replay results | Yes | +| `GET` | `/api/v1/record/{policyId}/run/details` | Returns details of the replay run | Yes | +| `POST` | `/api/v1/record/{policyId}/run/fast-forward` | Fast-forwards to a specific step in the replay | Yes | +| `POST` | `/api/v1/record/{policyId}/run/retry` | Retries the current step in the replay | Yes | +| `POST` | `/api/v1/record/{policyId}/run/skip` | Skips the current step in the replay | Yes | + +## Endpoints + +- [Start Recording](start-recording.md) +- [Stop Recording](stop-recording.md) +- [Get Recorded Actions](get-recorded-actions.md) +- [Get Recording](get-recording.md) +- [Run Record from ZIP File](run-record-from-zip-file.md) +- [Stop Running](stop-running.md) +- [Get Running Results](get-running-results.md) +- [Get Running Details](get-running-details.md) +- [Fast Forward](fast-forward.md) +- [Retry Step](retry-step.md) +- [Skip Step](skip-step.md) diff --git a/docs/guardian/standard-registry/policies/record-replay/record-replay-apis/get-recording.md b/docs/guardian/standard-registry/policies/record-replay/record-replay-apis/get-recording.md index bfedc285c9..172d1ddbb4 100644 --- a/docs/guardian/standard-registry/policies/record-replay/record-replay-apis/get-recording.md +++ b/docs/guardian/standard-registry/policies/record-replay/record-replay-apis/get-recording.md @@ -1,41 +1,51 @@ -# Get Recording +# Get Recording or Running Status -{% swagger method="get" path="" baseUrl="/record/{policyId}/status" summary="Get recording or running status." %} -{% swagger-description %} -Get recording or running status. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`GET /api/v1/record/{policyId}/status`** -{% swagger-parameter in="path" name="policyId" type="String" required="true" %} -policy ID -{% endswagger-parameter %} +Returns the current recording or running status for a policy. -{% swagger-parameter in="body" type="Object" required="true" %} -Object that contains options -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/RecordStatusDTO' -``` -{% endswagger-response %} +**Permission:** `Permissions.POLICIES_RECORD_ALL` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +--- -{% endswagger-response %} +## Request -{% swagger-response status="403: Forbidden" description="Forbidden" %} +### Path Parameters -{% endswagger-response %} +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `policyId` | string | Yes | The ID of the policy whose record status is being queried | -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "type": "RECORDING", + "policyId": "63e3e5e8a01b3c001234abcd", + "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "status": "STOPPED" +} ``` -{% endswagger-response %} -{% endswagger %} + +| Field | Type | Description | +|-------|------|-------------| +| `type` | string | Current mode: `RECORDING` or `RUNNING` | +| `policyId` | string | The policy identifier | +| `uuid` | string | Unique identifier for the current recording or run session | +| `status` | string | Session status: `NONE`, `RECORDING`, `RUNNING`, or `STOPPED` | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/record-replay/record-replay-apis/start-recording.md b/docs/guardian/standard-registry/policies/record-replay/record-replay-apis/start-recording.md index e91efcd3eb..b8762bb53c 100644 --- a/docs/guardian/standard-registry/policies/record-replay/record-replay-apis/start-recording.md +++ b/docs/guardian/standard-registry/policies/record-replay/record-replay-apis/start-recording.md @@ -1,41 +1,51 @@ # Start Recording -{% swagger method="post" path="" baseUrl="/record/{policyId}/recording/start" summary="Start recording." %} -{% swagger-description %} -Start recording. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /api/v1/record/{policyId}/recording/start`** -{% swagger-parameter in="path" name="policyId" type="String" required="true" %} -Policy ID -{% endswagger-parameter %} +Starts recording all API interactions with the specified policy session. -{% swagger-parameter in="body" type="Object" required="true" %} -Object that contains options -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - type: boolean -``` -{% endswagger-response %} +**Permission:** `Permissions.POLICIES_RECORD_ALL` + +--- -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +## Request -{% endswagger-response %} +### Path Parameters -{% swagger-response status="403: Forbidden" description="Forbidden" %} +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `policyId` | string | Yes | The ID of the policy to start recording | -{% endswagger-response %} +### Request Body -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} +```json +{} ``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `options` | object | No | Optional recording configuration options | + +--- + +## Response + +### Success Response + +**Status:** `202 Accepted` + +```json +true ``` -{% endswagger-response %} -{% endswagger %} + +Returns `true` when the recording session has been successfully initiated. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/record-replay/record-replay-apis/stop-recording.md b/docs/guardian/standard-registry/policies/record-replay/record-replay-apis/stop-recording.md index e2a4f52ce5..e0e57cf951 100644 --- a/docs/guardian/standard-registry/policies/record-replay/record-replay-apis/stop-recording.md +++ b/docs/guardian/standard-registry/policies/record-replay/record-replay-apis/stop-recording.md @@ -1,42 +1,54 @@ # Stop Recording -{% swagger method="post" path="" baseUrl=" /record/{policyId}/recording/stop" summary="Stop recording." %} -{% swagger-description %} -Stop recording. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /api/v1/record/{policyId}/recording/stop`** -{% swagger-parameter in="path" name="policyId" type="String" required="true" %} -Policy ID -{% endswagger-parameter %} +Stops the active recording session for a policy and returns the captured recording as a ZIP file. -{% swagger-parameter in="body" type="Object" required="true" %} -Object that contains options -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - type: string - format: binary +**Permission:** `Permissions.POLICIES_RECORD_ALL` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `policyId` | string | Yes | The ID of the policy whose recording is being stopped | + +### Request Body + +```json +{} ``` -{% endswagger-response %} -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `options` | object | No | Optional stop configuration options | + +--- + +## Response -{% endswagger-response %} +### Success Response -{% swagger-response status="403: Forbidden" description="Forbidden" %} +**Status:** `202 Accepted` -{% endswagger-response %} +Returns the completed recording packaged as a binary ZIP file. -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} ``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +Content-Disposition: attachment; filename= +Content-Type: application/zip + + ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/tagging/tagging-apis/README.md b/docs/guardian/standard-registry/policies/tagging/tagging-apis/README.md index 37e373aa93..d0bb78888a 100644 --- a/docs/guardian/standard-registry/policies/tagging/tagging-apis/README.md +++ b/docs/guardian/standard-registry/policies/tagging/tagging-apis/README.md @@ -1,2 +1,21 @@ # Tagging APIs +Endpoints for creating, searching, synchronizing, and deleting tags on Guardian policy entities. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `POST` | `/api/v1/tags` | Creates a new tag | Yes | +| `POST` | `/api/v1/tags/search` | Searches for tags matching the specified criteria | Yes | +| `DELETE` | `/api/v1/tags/{tagId}` | Deletes the specified tag | Yes | +| `GET` | `/api/v1/tags/synchronization` | Synchronizes tags from the Hedera network | Yes | + +## Endpoints + +- [Creating Tag](creating-tag.md) +- [Searching Tag](searching-tag.md) +- [Deleting Tag](deleting-tag.md) +- [Synchronization of Tags](synchronization-of-tags.md) diff --git a/docs/guardian/standard-registry/policies/tagging/tagging-apis/creating-tag.md b/docs/guardian/standard-registry/policies/tagging/tagging-apis/creating-tag.md index a0dea2db41..41a33e84f3 100644 --- a/docs/guardian/standard-registry/policies/tagging/tagging-apis/creating-tag.md +++ b/docs/guardian/standard-registry/policies/tagging/tagging-apis/creating-tag.md @@ -1,46 +1,66 @@ # Creating Tag -{% swagger method="post" path="" baseUrl="/tags/" summary="Creates new tag." %} -{% swagger-description %} -Creates new tag. -{% endswagger-description %} +**`POST /api/v1/tags`** -{% swagger-parameter in="body" type="Object" required="true" %} -Object that contains tag information. -{% endswagger-parameter %} +Creates a new tag and associates it with the specified entity. -{% swagger-response status="201: Created" description="Successful Operation" %} -``` -content: - application/json: - schema: - $ref: "#/components/schemas/Tag" -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="400: Bad Request" description="Bad Request" %} -``` -content: - application/json: - schema: - $ref: "#/components/schemas/Error" +**Permission:** `Permissions.TAGS_TAG_CREATE` + +--- + +## Request + +### Request Body + +```json +{ + "name": "example-tag", + "description": "A sample tag", + "entity": "PolicyDocument", + "target": "1706823489.123456789", + "localTarget": "63e3e5e8a01b3c001234abcd", + "uri": "https://example.com/tag-schema" +} ``` -{% endswagger-response %} -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | Yes | Human-readable tag name | +| `description` | string | No | Optional tag description | +| `entity` | string | Yes | Entity type the tag belongs to (e.g. `Schema`, `Policy`, `Token`, `Module`, `Contract`, `PolicyDocument`) | +| `target` | string | Yes | Hedera message ID of the target entity | +| `localTarget` | string | No | Local database ID of the target entity | +| `uri` | string | No | URI of the tag schema | -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} +## Response -{% endswagger-response %} +### Success Response -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: "#/components/schemas/Error" +**Status:** `201 Created` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "name": "example-tag", + "description": "A sample tag", + "entity": "PolicyDocument", + "target": "1706823489.123456789", + "localTarget": "63e3e5e8a01b3c001234abcd", + "uri": "https://example.com/tag-schema", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "status": "Draft" +} ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `400 Bad Request` | Malformed request body | +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/tagging/tagging-apis/deleting-tag.md b/docs/guardian/standard-registry/policies/tagging/tagging-apis/deleting-tag.md index 92f0334046..1ab3495602 100644 --- a/docs/guardian/standard-registry/policies/tagging/tagging-apis/deleting-tag.md +++ b/docs/guardian/standard-registry/policies/tagging/tagging-apis/deleting-tag.md @@ -1,37 +1,40 @@ # Deleting Tag -{% swagger method="delete" path="" baseUrl="/tags/{uuid}" summary="Delete tag." %} -{% swagger-description %} -Delete tag. -{% endswagger-description %} +**`DELETE /api/v1/tags/{uuid}`** -{% swagger-parameter in="path" name="uuid" type="String" required="true" %} -Tag identifier -{% endswagger-parameter %} +Deletes the tag with the specified UUID. -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - type: boolean -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +**Permission:** `Permissions.TAGS_TAG_CREATE` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} +## Request -{% endswagger-response %} +### Path Parameters -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: "#/components/schemas/Error" +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `uuid` | string | Yes | Unique identifier (UUID) of the tag to delete | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Invalid or missing `uuid` parameter | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/tagging/tagging-apis/searching-tag.md b/docs/guardian/standard-registry/policies/tagging/tagging-apis/searching-tag.md index 0f8fb9e07e..b1c36eb53e 100644 --- a/docs/guardian/standard-registry/policies/tagging/tagging-apis/searching-tag.md +++ b/docs/guardian/standard-registry/policies/tagging/tagging-apis/searching-tag.md @@ -1,54 +1,82 @@ -# Searching Tag +# Searching Tags -{% swagger method="post" path="" baseUrl="/tags/search" summary="Search tags." %} -{% swagger-description %} -Search tags. -{% endswagger-description %} +**`POST /api/v1/tags/search`** -{% swagger-parameter in="body" type="String" required="true" name="entity" %} -\[Schema, Policy, Token, Module, Contract, PolicyDocument] -{% endswagger-parameter %} +Searches for tags associated with one or more target entities of the given type. -{% swagger-parameter in="body" name="target" type="String" required="true" %} -targetId1 -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-parameter in="body" name="entity" type="String" required="true" %} -\[Schema, Policy, Token, Module, Contract, PolicyDocument] -{% endswagger-parameter %} +**Permission:** `Permissions.TAGS_TAG_READ` -{% swagger-parameter in="body" name="targets" type="String" required="true" %} -\[targetId1, targetId2] -{% endswagger-parameter %} +--- -{% swagger-response status="200: OK" description="Successful Operation" %} +## Request + +### Request Body + +Search for tags on a single target: + +```json +{ + "entity": "PolicyDocument", + "target": "1706823489.123456789" +} ``` -content: - application/json: - schema: - description: a (targetId, Tags) map. `targetId1` is an example key - properties: - targetId1: - $ref: "#/components/schemas/TagMap" - additionalProperties: - $ref: "#/components/schemas/TagMap" + +Search for tags on multiple targets: + +```json +{ + "entity": "PolicyDocument", + "targets": [ + "1706823489.123456789", + "1706823490.987654321" + ] +} ``` -{% endswagger-response %} -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `entity` | string | Yes | Entity type to search tags for. One of: `Schema`, `Policy`, `Token`, `Module`, `Contract`, `PolicyDocument` | +| `target` | string | No | Single target message ID. Required if `targets` is not provided | +| `targets` | string[] | No | Array of target message IDs. Required if `target` is not provided | +| `linkedItems` | boolean | No | Whether to include linked items in the result | -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} +## Response -{% endswagger-response %} +### Success Response -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: "#/components/schemas/Error" +**Status:** `200 OK` + +Returns a map of target IDs to their associated tag data: + +```json +{ + "1706823489.123456789": { + "entity": "PolicyDocument", + "target": "1706823489.123456789", + "refreshDate": "2024-02-01T12:00:00.000Z", + "tags": [ + { + "id": "63e3e5e8a01b3c001234abcd", + "name": "example-tag", + "entity": "PolicyDocument", + "target": "1706823489.123456789", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "status": "Published" + } + ] + } +} ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Missing or invalid `entity`, `target`, or `targets` field | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/tagging/tagging-apis/synchronization-of-tags.md b/docs/guardian/standard-registry/policies/tagging/tagging-apis/synchronization-of-tags.md index c245a7d2cd..75fd0297d6 100644 --- a/docs/guardian/standard-registry/policies/tagging/tagging-apis/synchronization-of-tags.md +++ b/docs/guardian/standard-registry/policies/tagging/tagging-apis/synchronization-of-tags.md @@ -1,41 +1,63 @@ -# Synchronization of tags +# Synchronization of Tags -{% swagger method="post" path="" baseUrl="/tags/synchronization" summary="synchronization." %} -{% swagger-description %} -synchronization. -{% endswagger-description %} +**`POST /api/v1/tags/synchronization`** -{% swagger-parameter in="body" name="entity" type="String" required="true" %} -\[Schema, Policy, Token, Module, Contract, PolicyDocument] -{% endswagger-parameter %} +Synchronizes tags for a target entity with an external Hedera network, refreshing the local cache. -{% swagger-parameter in="body" name="target" type="String" required="true" %} -targetId -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - $ref: "#/components/schemas/TagMap" -``` -{% endswagger-response %} - -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +**Permission:** `Permissions.TAGS_TAG_READ` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} +## Request -{% endswagger-response %} +### Request Body -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} +```json +{ + "entity": "PolicyDocument", + "target": "1706823489.123456789" +} ``` -content: - application/json: - schema: - $ref: "#/components/schemas/Error" + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `entity` | string | Yes | Entity type to synchronize tags for. One of: `Schema`, `Policy`, `Token`, `Module`, `Contract`, `PolicyDocument` | +| `target` | string | Yes | Hedera message ID of the target entity | +| `linkedItems` | boolean | No | Whether to include linked items during synchronization | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "entity": "PolicyDocument", + "target": "1706823489.123456789", + "refreshDate": "2024-02-01T12:00:00.000Z", + "tags": [ + { + "id": "63e3e5e8a01b3c001234abcd", + "name": "example-tag", + "entity": "PolicyDocument", + "target": "1706823489.123456789", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "status": "Published" + } + ] +} ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Missing or invalid `entity` or `target` field | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/themes/themes-apis/README.md b/docs/guardian/standard-registry/policies/themes/themes-apis/README.md index 087465f6ac..bec5648eee 100644 --- a/docs/guardian/standard-registry/policies/themes/themes-apis/README.md +++ b/docs/guardian/standard-registry/policies/themes/themes-apis/README.md @@ -1,2 +1,25 @@ # Themes APIs +Endpoints for creating, updating, importing, exporting, and deleting visual themes used in the Guardian policy editor UI. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `GET` | `/api/v1/themes` | Returns all themes for the current user | Yes | +| `POST` | `/api/v1/themes` | Creates a new theme | Yes | +| `PUT` | `/api/v1/themes/{themeId}` | Updates a theme configuration | Yes | +| `DELETE` | `/api/v1/themes/{themeId}` | Deletes a theme | Yes | +| `GET` | `/api/v1/themes/{themeId}/export/file` | Exports a theme as a ZIP file | Yes | +| `POST` | `/api/v1/themes/import/file` | Imports a theme from a ZIP file | Yes | + +## Endpoints + +- [Returning All Themes](returning-all-themes.md) +- [Creating Theme](creating-theme.md) +- [Updating Theme Configuration](updating-theme-configuration.md) +- [Deleting Theme](deleting-theme.md) +- [Returning ZIP File Containing Themes](returning-zip-file-containing-themes.md) +- [Importing Theme](importing-theme.md) diff --git a/docs/guardian/standard-registry/policies/tools/tools-apis/README.md b/docs/guardian/standard-registry/policies/tools/tools-apis/README.md index 6f190987ae..4361d19dfd 100644 --- a/docs/guardian/standard-registry/policies/tools/tools-apis/README.md +++ b/docs/guardian/standard-registry/policies/tools/tools-apis/README.md @@ -1,2 +1,52 @@ # Tools APIs +Endpoints for creating, managing, importing, exporting, and publishing Guardian policy tools. Tools are reusable policy components that encapsulate specific functionality. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** Standard Registry role required for write operations. + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `GET` | `/api/v1/tools` | Returns all tools | Yes | +| `POST` | `/api/v1/tools` | Creates a new tool | Yes | +| `GET` | `/api/v1/tools/{id}` | Returns the tool configuration | Yes | +| `PUT` | `/api/v1/tools/{id}` | Updates the tool configuration | Yes | +| `DELETE` | `/api/v1/tools/{id}` | Deletes a tool | Yes | +| `GET` | `/api/v1/tools/{id}/export/file` | Exports a tool as a ZIP file | Yes | +| `GET` | `/api/v1/tools/{id}/export/message` | Returns the tool Hedera message ID | Yes | +| `POST` | `/api/v1/tools/import/file` | Imports a tool from a ZIP file | Yes | +| `POST` | `/api/v1/tools/import/message` | Imports a tool from an IPFS message ID | Yes | +| `POST` | `/api/v1/tools/import/file/preview` | Previews a tool from a ZIP file | Yes | +| `POST` | `/api/v1/tools/import/message/preview` | Previews a tool from an IPFS message ID | Yes | +| `PUT` | `/api/v1/tools/{id}/publish` | Publishes a tool to IPFS | Yes | +| `POST` | `/api/v1/tools/push` | Creates a new tool asynchronously | Yes | +| `POST` | `/api/v1/tools/{id}/validate` | Validates a tool | Yes | +| `GET` | `/api/v1/tools/menu/all` | Returns the tools available in the menu | Yes | + +## Endpoints + +- [Returns List of Tools](returns-list-of-tools.md) +- [Returns List of Tools (v1)](returns-list-of-tools-1.md) +- [Creating New Tool](creating-new-tool.md) +- [Creating New Tool Asynchronously](creating-new-tool-asynchronously.md) +- [Retrieves Tool Configuration](retrieves-tool-configuration.md) +- [Updates Tool Configuration](updates-tool-configuration.md) +- [Deletes the Tool](deletes-the-tool.md) +- [Returns Tools and Its Artifacts in ZIP Format](returns-tools-and-its-artifacts-in-zip-format.md) +- [Retrieves Hedera Message ID](retrieves-hedera-message-id.md) +- [Importing Tool from a ZIP File](importing-tool-from-a-zip-file.md) +- [Importing Tool from ZIP](importing-tool-from-zip.md) +- [Imported Tool from IPFS](imported-tool-from-ipfs.md) +- [Previews Imported Tool from ZIP](previews-imported-tool-from-zip.md) +- [Previews Imported Tool from IPFS](previews-imported-tool-from-ipfs.md) +- [Importing Tool from a ZIP File Asynchronously](importing-tool-from-a-zip-file-asynchronously.md) +- [Imports New Tool from ZIP Asynchronously](imports-new-tool-from-zip-asynchronously.md) +- [Imports New Tool from IPFS Asynchronously](imports-new-tool-from-ipfs-asynchronously.md) +- [Publishes Tool onto IPFS](publishes-tool-onto-ipfs.md) +- [Publishes Tool into IPFS Asynchronously](publishes-tool-into-ipfs-asynchronously.md) +- [Validates Selected Tool](validates-selected-tool.md) +- [Return Policy to Editing](return-policy-to-editing.-only-users-with-the-standard-registry-can-make-request.md) +- [Run Policy Without Making Any Persistent Changes](run-policy-without-making-any-persistent-changes-or-executing-transaction..md) diff --git a/docs/guardian/standard-registry/policies/tools/tools-apis/creating-new-tool-asynchronously.md b/docs/guardian/standard-registry/policies/tools/tools-apis/creating-new-tool-asynchronously.md index 5f6cff745a..e5093f4a2c 100644 --- a/docs/guardian/standard-registry/policies/tools/tools-apis/creating-new-tool-asynchronously.md +++ b/docs/guardian/standard-registry/policies/tools/tools-apis/creating-new-tool-asynchronously.md @@ -1,25 +1,58 @@ -# Creating new tool asynchronously +# Creating New Tool Asynchronously -{% swagger method="post" path="" baseUrl="/tools/push" summary="Creates a new tool." %} -{% swagger-description %} -Creates a new tool. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /api/v1/tools/push`** -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/TaskDTO' -``` -{% endswagger-response %} +Creates a new tool asynchronously and returns a task ID for polling the result. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.TOOLS_TOOL_CREATE` -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} +--- + +## Request + +### Request Body + +```json +{ + "name": "My Tool", + "description": "Tool description", + "config": { + "blockType": "tool", + "children": [] + } +} ``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | Yes | Human-readable name of the tool | +| `description` | string | No | Brief description of the tool's purpose | +| `config` | object | Yes | Tool configuration object; `blockType` must be `"tool"` | + +--- + +## Response + +### Success Response + +**Status:** `202 Accepted` + +```json +{ + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Create tool" +} ``` -{% endswagger-response %} -{% endswagger %} + +Poll `GET /tasks/{taskId}` to retrieve the result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Invalid tool config (e.g., missing or incorrect `blockType`) | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/tools/tools-apis/creating-new-tool.md b/docs/guardian/standard-registry/policies/tools/tools-apis/creating-new-tool.md index d1682f16a1..bddba5caa5 100644 --- a/docs/guardian/standard-registry/policies/tools/tools-apis/creating-new-tool.md +++ b/docs/guardian/standard-registry/policies/tools/tools-apis/creating-new-tool.md @@ -1,25 +1,65 @@ -# Creating new Tool +# Creating New Tool -{% swagger method="post" path="" baseUrl="/tools" summary="Creates a new tool." %} -{% swagger-description %} -Creates a new tool. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /api/v1/tools`** -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/ToolDTO' -``` -{% endswagger-response %} +Creates a new tool for the current Standard Registry user. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.TOOLS_TOOL_CREATE` -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} +--- + +## Request + +### Request Body + +```json +{ + "name": "My Tool", + "description": "Tool description", + "config": { + "blockType": "tool", + "children": [] + } +} ``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | Yes | Human-readable name of the tool | +| `description` | string | No | Brief description of the tool's purpose | +| `config` | object | Yes | Tool configuration object; `blockType` must be `"tool"` | + +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "name": "My Tool", + "description": "Tool description", + "status": "DRAFT", + "creator": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "topicId": "0.0.5000001", + "config": { + "blockType": "tool", + "children": [] + } +} ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Invalid tool config (e.g., missing or incorrect `blockType`) | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/tools/tools-apis/deletes-the-tool.md b/docs/guardian/standard-registry/policies/tools/tools-apis/deletes-the-tool.md index 57fc7b3ecb..503a5f3441 100644 --- a/docs/guardian/standard-registry/policies/tools/tools-apis/deletes-the-tool.md +++ b/docs/guardian/standard-registry/policies/tools/tools-apis/deletes-the-tool.md @@ -1,24 +1,42 @@ # Deletes the Tool -{% swagger method="delete" path="" baseUrl="/tools/{id}" summary="Deletes the tool." %} -{% swagger-description %} -Deletes the tool with the provided tool ID. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`DELETE /api/v1/tools/{id}`** -{% swagger-parameter in="path" name="id" type="String" required="true" %} -Tool ID -{% endswagger-parameter %} +Deletes the tool with the provided tool ID. -{% swagger-response status="200: OK" description="Successful Operation" %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% endswagger-response %} +**Permission:** `Permissions.TOOLS_TOOL_DELETE` -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `id` | string | Yes | Tool ID (MongoDB ObjectId) | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +Returns `true` on successful deletion. + +```json +true ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | `id` is missing or invalid | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/tools/tools-apis/imported-tool-from-ipfs.md b/docs/guardian/standard-registry/policies/tools/tools-apis/imported-tool-from-ipfs.md index 114511a587..21d95b9e59 100644 --- a/docs/guardian/standard-registry/policies/tools/tools-apis/imported-tool-from-ipfs.md +++ b/docs/guardian/standard-registry/policies/tools/tools-apis/imported-tool-from-ipfs.md @@ -1,33 +1,55 @@ -# Imported Tool from IPFS +# Import Tool from IPFS -{% swagger method="post" path="" baseUrl="/tools/import/message" summary="Imports new tool from IPFS." %} -{% swagger-description %} -Imports new tool and all associated artifacts from IPFS into the local DB. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /api/v1/tools/import/message`** -{% swagger-response status="200: OK" description="Successful Operation" %} -``` - content: - application/json: - schema: - $ref: '#/components/schemas/ToolDTO' -``` -{% endswagger-response %} +Imports a new tool and all associated artifacts from IPFS into the local database using a Hedera message ID. + +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +**Permission:** `Permissions.TOOLS_TOOL_CREATE` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} +## Request -{% endswagger-response %} +### Request Body -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} +```json +{ + "messageId": "1700000000.000000001" +} ``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `messageId` | string | Yes | Hedera message ID referencing the tool on IPFS | + +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "name": "Imported Tool", + "description": "Tool imported from IPFS", + "status": "PUBLISHED", + "creator": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "topicId": "0.0.5000001", + "messageId": "1700000000.000000001" +} ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | `messageId` is missing from the request body | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/tools/tools-apis/importing-tool-from-a-zip-file-asynchronously.md b/docs/guardian/standard-registry/policies/tools/tools-apis/importing-tool-from-a-zip-file-asynchronously.md index 7fe5cee4f6..cbed0a8590 100644 --- a/docs/guardian/standard-registry/policies/tools/tools-apis/importing-tool-from-a-zip-file-asynchronously.md +++ b/docs/guardian/standard-registry/policies/tools/tools-apis/importing-tool-from-a-zip-file-asynchronously.md @@ -1,5 +1,45 @@ -# Importing Tool from a Zip file asynchronously +# Importing Tool from a Zip File Asynchronously (with Metadata) -{% swagger src="../../../../../.gitbook/assets/swagger (4).yaml" path="/tools/push/import/file-metadata" method="post" %} -[swagger (4).yaml](<../../../../../.gitbook/assets/swagger (4).yaml>) -{% endswagger %} +**`POST /api/v1/tools/push/import/file-metadata`** + +Asynchronously imports a new tool from a multipart zip file with optional metadata, and returns a task ID for polling the result. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.TOOL_MIGRATION_CREATE` + +--- + +## Request + +**Content-Type:** `multipart/form-data` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `file` | binary | Yes | ZIP file containing the tool configuration | +| `metadata` | binary | No | JSON metadata file for the tool migration | + +--- + +## Response + +### Success Response + +**Status:** `202 Accepted` + +```json +{ + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Import tool file" +} +``` + +Poll `GET /tasks/{taskId}` to retrieve the result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure or missing tool file | diff --git a/docs/guardian/standard-registry/policies/tools/tools-apis/importing-tool-from-a-zip-file.md b/docs/guardian/standard-registry/policies/tools/tools-apis/importing-tool-from-a-zip-file.md index 0b22c0c001..a59c203481 100644 --- a/docs/guardian/standard-registry/policies/tools/tools-apis/importing-tool-from-a-zip-file.md +++ b/docs/guardian/standard-registry/policies/tools/tools-apis/importing-tool-from-a-zip-file.md @@ -1,5 +1,48 @@ -# Importing Tool from a Zip file +# Importing Tool from a Zip File (with Metadata) -{% swagger src="../../../../../.gitbook/assets/swagger (4).yaml" path="/tools/import/file-metadata" method="post" %} -[swagger (4).yaml](<../../../../../.gitbook/assets/swagger (4).yaml>) -{% endswagger %} +**`POST /api/v1/tools/import/file-metadata`** + +Imports a new tool and all associated artifacts from a multipart zip file upload, with an optional metadata file. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.TOOL_MIGRATION_CREATE` + +--- + +## Request + +**Content-Type:** `multipart/form-data` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `file` | binary | Yes | ZIP file containing the tool configuration | +| `metadata` | binary | No | JSON metadata file for the tool migration | + +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "name": "Imported Tool", + "description": "Tool imported from zip", + "status": "DRAFT", + "creator": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "topicId": "0.0.5000001" +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure or missing tool file in form data | diff --git a/docs/guardian/standard-registry/policies/tools/tools-apis/importing-tool-from-zip.md b/docs/guardian/standard-registry/policies/tools/tools-apis/importing-tool-from-zip.md index d11ba96309..d00833b725 100644 --- a/docs/guardian/standard-registry/policies/tools/tools-apis/importing-tool-from-zip.md +++ b/docs/guardian/standard-registry/policies/tools/tools-apis/importing-tool-from-zip.md @@ -1,33 +1,47 @@ # Importing Tool from Zip -{% swagger method="post" path="" baseUrl="/tools/import/file" summary="Imports new tool from a zip file." %} -{% swagger-description %} -Imports new tool and all associated artifacts, such as schemas and VCs, from the provided zip file into the local DB. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /api/v1/tools/import/file`** -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/ToolDTO' -``` -{% endswagger-response %} +Imports a new tool and all associated artifacts such as schemas and VCs from the provided zip file into the local database. -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% endswagger-response %} +**Permission:** `Permissions.TOOLS_TOOL_CREATE` -{% swagger-response status="403: Forbidden" description="Forbidden" %} +--- -{% endswagger-response %} +## Request -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +### Request Body + +Send the raw ZIP file bytes as the request body. + +**Content-Type:** `application/octet-stream` + +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "name": "Imported Tool", + "description": "Tool imported from zip", + "status": "DRAFT", + "creator": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "topicId": "0.0.5000001" +} ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/tools/tools-apis/imports-new-tool-from-ipfs-asynchronously.md b/docs/guardian/standard-registry/policies/tools/tools-apis/imports-new-tool-from-ipfs-asynchronously.md index 3ccfff74a1..7dbe5d4a0b 100644 --- a/docs/guardian/standard-registry/policies/tools/tools-apis/imports-new-tool-from-ipfs-asynchronously.md +++ b/docs/guardian/standard-registry/policies/tools/tools-apis/imports-new-tool-from-ipfs-asynchronously.md @@ -1,33 +1,51 @@ -# Imports new tool from IPFS Asynchronously +# Imports New Tool from IPFS Asynchronously -{% swagger method="post" path="" baseUrl="/tools/push/import/message" summary="Imports new tool from IPFS." %} -{% swagger-description %} -Imports new tool and all associated artifacts from IPFS into the local DB. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /api/v1/tools/push/import/message`** -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/TaskDTO' -``` -{% endswagger-response %} +Asynchronously imports a new tool and all associated artifacts from IPFS using a Hedera message ID, and returns a task ID for polling the result. + +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +**Permission:** `Permissions.TOOLS_TOOL_CREATE` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} +## Request -{% endswagger-response %} +### Request Body -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} +```json +{ + "messageId": "1700000000.000000001" +} ``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `messageId` | string | Yes | Hedera message ID referencing the tool on IPFS | + +--- + +## Response + +### Success Response + +**Status:** `202 Accepted` + +```json +{ + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Import tool message" +} ``` -{% endswagger-response %} -{% endswagger %} + +Poll `GET /tasks/{taskId}` to retrieve the result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | `messageId` is missing from the request body | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/tools/tools-apis/imports-new-tool-from-zip-asynchronously.md b/docs/guardian/standard-registry/policies/tools/tools-apis/imports-new-tool-from-zip-asynchronously.md index cc71aecb33..955cf7434b 100644 --- a/docs/guardian/standard-registry/policies/tools/tools-apis/imports-new-tool-from-zip-asynchronously.md +++ b/docs/guardian/standard-registry/policies/tools/tools-apis/imports-new-tool-from-zip-asynchronously.md @@ -1,33 +1,44 @@ -# Imports new tool from Zip Asynchronously +# Imports New Tool from Zip Asynchronously -{% swagger method="post" path="" baseUrl="/tools/push/import/file" summary="Imports new tool from a zip file." %} -{% swagger-description %} -Imports new tool and all associated artifacts, such as schemas and VCs, from the provided zip file into the local DB. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /api/v1/tools/push/import/file`** -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/TaskDTO' -``` -{% endswagger-response %} +Asynchronously imports a new tool and all associated artifacts from the provided zip file, and returns a task ID for polling the result. -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% endswagger-response %} +**Permission:** `Permissions.TOOLS_TOOL_CREATE` -{% swagger-response status="403: Forbidden" description="Forbidden" %} +--- -{% endswagger-response %} +## Request -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +### Request Body + +Send the raw ZIP file bytes as the request body. + +**Content-Type:** `application/octet-stream` + +--- + +## Response + +### Success Response + +**Status:** `202 Accepted` + +```json +{ + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Import tool file" +} ``` -{% endswagger-response %} -{% endswagger %} + +Poll `GET /tasks/{taskId}` to retrieve the result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/tools/tools-apis/previews-imported-tool-from-ipfs.md b/docs/guardian/standard-registry/policies/tools/tools-apis/previews-imported-tool-from-ipfs.md index b6cef5aa53..bb976cc7ac 100644 --- a/docs/guardian/standard-registry/policies/tools/tools-apis/previews-imported-tool-from-ipfs.md +++ b/docs/guardian/standard-registry/policies/tools/tools-apis/previews-imported-tool-from-ipfs.md @@ -1,33 +1,56 @@ # Previews Imported Tool from IPFS -{% swagger method="post" path="" baseUrl="/tools/import/message/preview" summary="Previews Imported new tool from IPFS." %} -{% swagger-description %} -Previews Imported new tool and all associated artifacts from IPFS into the local DB. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /api/v1/tools/import/message/preview`** -{% swagger-response status="200: OK" description="Successful Operation" %} -``` - content: - application/json: - schema: - type: object -``` -{% endswagger-response %} +Returns a preview of the tool that would be imported from IPFS using a Hedera message ID, without persisting any changes. + +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +**Permission:** `Permissions.TOOLS_TOOL_CREATE` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} +## Request -{% endswagger-response %} +### Request Body -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} +```json +{ + "messageId": "1700000000.000000001" +} ``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `messageId` | string | Yes | Hedera message ID referencing the tool on IPFS | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "tool": { + "name": "Preview Tool", + "description": "Tool preview from IPFS", + "config": { + "blockType": "tool", + "children": [] + } + }, + "schemas": [] +} ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | `messageId` is missing from the request body | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/tools/tools-apis/previews-imported-tool-from-zip.md b/docs/guardian/standard-registry/policies/tools/tools-apis/previews-imported-tool-from-zip.md index 94f5d12354..51852a9c45 100644 --- a/docs/guardian/standard-registry/policies/tools/tools-apis/previews-imported-tool-from-zip.md +++ b/docs/guardian/standard-registry/policies/tools/tools-apis/previews-imported-tool-from-zip.md @@ -1,33 +1,49 @@ # Previews Imported Tool from Zip -{% swagger method="post" path="" baseUrl="/tools/import/file/preview" summary="Previews Imported new tool from a zip file." %} -{% swagger-description %} -Previews Imported new tool and all associated artifacts, such as schemas and VCs, from the provided zip file into the local DB. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /api/v1/tools/import/file/preview`** -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - type: object -``` -{% endswagger-response %} +Returns a preview of the tool that would be imported from the provided zip file, without persisting any changes. -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% endswagger-response %} +**Permission:** `Permissions.TOOLS_TOOL_CREATE` -{% swagger-response status="403: Forbidden" description="Forbidden" %} +--- -{% endswagger-response %} +## Request -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +### Request Body + +Send the raw ZIP file bytes as the request body. + +**Content-Type:** `application/octet-stream` + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "tool": { + "name": "Preview Tool", + "description": "Tool preview from zip", + "config": { + "blockType": "tool", + "children": [] + } + }, + "schemas": [] +} ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/tools/tools-apis/publishes-tool-into-ipfs-asynchronously.md b/docs/guardian/standard-registry/policies/tools/tools-apis/publishes-tool-into-ipfs-asynchronously.md index 6608cf136f..7f9f8d8489 100644 --- a/docs/guardian/standard-registry/policies/tools/tools-apis/publishes-tool-into-ipfs-asynchronously.md +++ b/docs/guardian/standard-registry/policies/tools/tools-apis/publishes-tool-into-ipfs-asynchronously.md @@ -1,37 +1,57 @@ -# Publishes Tool into IPFS asynchronously +# Publishes Tool onto IPFS Asynchronously -{% swagger method="put" path="" baseUrl="/tools/{id}/push/publish" summary="Publishes the tool onto IPFS." %} -{% swagger-description %} -Publishes the tool with the specified (internal) tool ID onto IPFS, sends a message featuring its IPFS CID into the corresponding Hedera topic. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`PUT /api/v1/tools/{id}/push/publish`** -{% swagger-parameter in="path" name="Tool ID" type="String" required="true" %} -Tool ID -{% endswagger-parameter %} +Asynchronously publishes the tool with the specified tool ID onto IPFS and returns a task ID for polling the result. -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/TaskDTO' -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.TOOLS_TOOL_REVIEW` + +--- -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +## Request -{% endswagger-response %} +### Path Parameters -{% swagger-response status="403: Forbidden" description="Forbidden" %} +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `id` | string | Yes | Tool ID (MongoDB ObjectId) | -{% endswagger-response %} +### Request Body -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} +```json +{ + "version": "1.0.0" +} ``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `version` | string | Yes | Version string to assign to the published tool | + +--- + +## Response + +### Success Response + +**Status:** `202 Accepted` + +```json +{ + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Publish tool" +} ``` -{% endswagger-response %} -{% endswagger %} + +Poll `GET /tasks/{taskId}` to retrieve the result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | `id` is missing or invalid | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/tools/tools-apis/publishes-tool-onto-ipfs.md b/docs/guardian/standard-registry/policies/tools/tools-apis/publishes-tool-onto-ipfs.md index 9215d4e021..e63f827667 100644 --- a/docs/guardian/standard-registry/policies/tools/tools-apis/publishes-tool-onto-ipfs.md +++ b/docs/guardian/standard-registry/policies/tools/tools-apis/publishes-tool-onto-ipfs.md @@ -1,37 +1,55 @@ # Publishes Tool onto IPFS -{% swagger method="put" path="" baseUrl="/tools/{id}/publish" summary="Publishes the tool onto IPFS." %} -{% swagger-description %} -Publishes the tool with the specified (internal) tool ID onto IPFS, sends a message featuring its IPFS CID into the corresponding Hedera topic. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`PUT /api/v1/tools/{id}/publish`** -{% swagger-parameter in="path" name="id" type="String" required="true" %} -Tool ID -{% endswagger-parameter %} +Publishes the tool with the specified tool ID onto IPFS and sends a message featuring its IPFS CID into the corresponding Hedera topic. -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/ToolDTO' -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.TOOLS_TOOL_REVIEW` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +--- -{% endswagger-response %} +## Request -{% swagger-response status="403: Forbidden" description="Forbidden" %} +### Path Parameters -{% endswagger-response %} +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `id` | string | Yes | Tool ID (MongoDB ObjectId) | -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} +### Request Body + +```json +{ + "version": "1.0.0" +} ``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `version` | string | Yes | Version string to assign to the published tool | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "valid": true, + "results": [] +} ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | `id` is missing or invalid | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/tools/tools-apis/retrieves-hedera-message-id.md b/docs/guardian/standard-registry/policies/tools/tools-apis/retrieves-hedera-message-id.md index f98fb4a27b..c7d17651bf 100644 --- a/docs/guardian/standard-registry/policies/tools/tools-apis/retrieves-hedera-message-id.md +++ b/docs/guardian/standard-registry/policies/tools/tools-apis/retrieves-hedera-message-id.md @@ -1,37 +1,45 @@ # Retrieves Hedera Message ID -{% swagger method="get" path="" baseUrl="/tools/{id}/export/message" summary="Return Hedera message ID for the specified published tool." %} -{% swagger-description %} -Returns the Hedera message ID for the specified tool published onto IPFS. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`GET /api/v1/tools/{id}/export/message`** -{% swagger-parameter in="path" name="id" type="String" required="true" %} -Tool ID -{% endswagger-parameter %} +Returns the Hedera message ID for the specified tool published onto IPFS. -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - type: object -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +**Permission:** `Permissions.TOOLS_TOOL_READ` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} +## Request -{% endswagger-response %} +### Path Parameters -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `id` | string | Yes | Tool ID (MongoDB ObjectId) | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "name": "My Tool", + "messageId": "1700000000.000000001", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001" +} ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | `id` is missing or invalid | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/tools/tools-apis/retrieves-tool-configuration.md b/docs/guardian/standard-registry/policies/tools/tools-apis/retrieves-tool-configuration.md index 78dfbeae60..5d906e0e66 100644 --- a/docs/guardian/standard-registry/policies/tools/tools-apis/retrieves-tool-configuration.md +++ b/docs/guardian/standard-registry/policies/tools/tools-apis/retrieves-tool-configuration.md @@ -1,37 +1,52 @@ # Retrieves Tool Configuration -{% swagger method="get" path="" baseUrl="/tools/{id}" summary="Retrieves tool configuration." %} -{% swagger-description %} -Retrieves tool configuration for the specified tool ID. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`GET /api/v1/tools/{id}`** -{% swagger-parameter in="path" name="id" type="String" required="true" %} -Tool ID -{% endswagger-parameter %} +Retrieves the full configuration for a specific tool by its ID. -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/ToolDTO' -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +**Permission:** `Permissions.TOOLS_TOOL_READ` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} +## Request -{% endswagger-response %} +### Path Parameters -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `id` | string | Yes | Tool ID (MongoDB ObjectId) | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "name": "My Tool", + "description": "Tool description", + "status": "DRAFT", + "creator": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "topicId": "0.0.5000001", + "config": { + "blockType": "tool", + "children": [] + } +} ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | `id` is missing or invalid | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/tools/tools-apis/return-policy-to-editing.-only-users-with-the-standard-registry-can-make-request.md b/docs/guardian/standard-registry/policies/tools/tools-apis/return-policy-to-editing.-only-users-with-the-standard-registry-can-make-request.md index 7061ccadb6..1eb7469883 100644 --- a/docs/guardian/standard-registry/policies/tools/tools-apis/return-policy-to-editing.-only-users-with-the-standard-registry-can-make-request.md +++ b/docs/guardian/standard-registry/policies/tools/tools-apis/return-policy-to-editing.-only-users-with-the-standard-registry-can-make-request.md @@ -1,63 +1,43 @@ -# Return policy to editing. Only users with the Standard Registry can make request +# Return Tool to Draft (Editing) -`PUT` `/tools/{id}/draft` +**`PUT /api/v1/tools/{id}/draft`** -Return policy to editing. Only users with the Standard Registry role are\ -allowed to make the request. +Returns a published or dry-run tool back to draft (editing) status. -**Headers** +**Authentication:** Bearer token required (`Authorization: Bearer `) -| Name | Value | -| ------------- | ------------------ | -| Content-Type | `application/json` | -| Authorization | `Bearer ` | +**Permission:** `Permissions.TOOLS_TOOL_UPDATE` -**Body** +--- -| Name | Type | Description | -| ---- | ------ | ----------- | -| id | string | Tool ID | +## Request -**Response** +### Path Parameters -{% tabs %} -{% tab title="200" %} -```json5 -{ - description: Successful operation. - content: - application/json: - schema: - $ref: '#/components/schemas/ToolValidationDTO' -} -``` -{% endtab %} +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `id` | string | Yes | Tool ID (MongoDB ObjectId) | -{% tab title="401" %} -```json5 -{ - description: Unauthorized. -} -``` -{% endtab %} +--- -{% tab title="403" %} -```json5 -{ -description: Forbidden. -} -``` -{% endtab %} +## Response + +### Success Response -{% tab title="500" %} -```json5 +**Status:** `200 OK` + +```json { -description: Internal server error. - content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' + "valid": true, + "results": [] } ``` -{% endtab %} -{% endtabs %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | `id` is missing or invalid | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/tools/tools-apis/returns-list-of-tools-1.md b/docs/guardian/standard-registry/policies/tools/tools-apis/returns-list-of-tools-1.md index de83e5fcd2..4603f660d0 100644 --- a/docs/guardian/standard-registry/policies/tools/tools-apis/returns-list-of-tools-1.md +++ b/docs/guardian/standard-registry/policies/tools/tools-apis/returns-list-of-tools-1.md @@ -1,33 +1,46 @@ -# Returns List of Tools +# Returns Tools Menu -{% swagger method="get" path="" baseUrl="/tools/menu/all" summary="Return a list of tools." %} -{% swagger-description %} -Returns tools menu. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`GET /api/v1/tools/menu/all`** -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - type: array -``` -{% endswagger-response %} +Returns a list of all available tools for use in the policy editor menu. -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% endswagger-response %} +**Permission:** `Permissions.POLICIES_POLICY_UPDATE`, `Permissions.MODULES_MODULE_UPDATE`, or `Permissions.TOOLS_TOOL_UPDATE` -{% swagger-response status="403: Forbidden" description="Forbidden" %} +--- -{% endswagger-response %} +## Request -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +No request parameters. + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "name": "Example Tool", + "description": "A sample tool", + "status": "PUBLISHED", + "creator": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "topicId": "0.0.5000001", + "messageId": "1700000000.000000001" + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/tools/tools-apis/returns-list-of-tools.md b/docs/guardian/standard-registry/policies/tools/tools-apis/returns-list-of-tools.md index d456b4396c..91d5733527 100644 --- a/docs/guardian/standard-registry/policies/tools/tools-apis/returns-list-of-tools.md +++ b/docs/guardian/standard-registry/policies/tools/tools-apis/returns-list-of-tools.md @@ -1,33 +1,53 @@ -# Returns list of tools +# Returns List of Tools -{% swagger method="get" path="" baseUrl="/tools" summary="Return a list of all tools." %} -{% swagger-description %} -Returns all tools. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`GET /api/v1/tools`** -{% swagger-parameter in="query" name="pageSize" type="number" %} -The numbers of items to return -{% endswagger-parameter %} +Returns a paginated list of all tools owned by the current Standard Registry user. -{% swagger-parameter in="query" name="pageIndex" type="number" %} -The number of pages to skip before starting to collect the result set -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/ToolDTO' -``` -{% endswagger-response %} +**Permission:** `Permissions.TOOLS_TOOL_READ` -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +--- + +## Request + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `pageIndex` | number | No | 0 | The number of pages to skip before starting to collect the result set | +| `pageSize` | number | No | 25 | The number of items to return | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +Returns an array of tool objects. The total item count is provided in the `X-Total-Count` response header. + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "name": "Example Tool", + "description": "A sample tool", + "status": "DRAFT", + "creator": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "topicId": "0.0.5000001", + "messageId": "1700000000.000000001" + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/tools/tools-apis/returns-tools-and-its-artifacts-in-zip-format.md b/docs/guardian/standard-registry/policies/tools/tools-apis/returns-tools-and-its-artifacts-in-zip-format.md index 496ae79017..a2dfe21bbe 100644 --- a/docs/guardian/standard-registry/policies/tools/tools-apis/returns-tools-and-its-artifacts-in-zip-format.md +++ b/docs/guardian/standard-registry/policies/tools/tools-apis/returns-tools-and-its-artifacts-in-zip-format.md @@ -1,32 +1,45 @@ -# Returns Tools and its artifacts in zip format +# Returns Tool and Its Artifacts in Zip Format -{% swagger method="get" path="" baseUrl="/tools/{id}/export/file" summary="Return tool and its artifacts in a zip file format for the specified tool." %} -{% swagger-description %} -Returns a zip file containing the published tool and all associated artifacts, i.e. schemas and VCs. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`GET /api/v1/tools/{id}/export/file`** -{% swagger-parameter in="path" name="id" type="String" required="true" %} -Tool ID -{% endswagger-parameter %} +Returns a zip file containing the published tool and all associated artifacts such as schemas and VCs. -{% swagger-response status="200: OK" description="Successful operation. Response zip file." %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% endswagger-response %} +**Permission:** `Permissions.TOOLS_TOOL_READ` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +--- -{% endswagger-response %} +## Request -{% swagger-response status="403: Forbidden" description="Forbidden" %} +### Path Parameters -{% endswagger-response %} +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `id` | string | Yes | Tool ID (MongoDB ObjectId) | -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' -``` -{% endswagger-response %} -{% endswagger %} +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +Returns a binary ZIP file. + +**Response Headers:** + +| Header | Value | +|--------|-------| +| `Content-Type` | `application/zip` | +| `Content-Disposition` | `attachment; filename=tool_` | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | `id` is missing or invalid | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/tools/tools-apis/run-policy-without-making-any-persistent-changes-or-executing-transaction..md b/docs/guardian/standard-registry/policies/tools/tools-apis/run-policy-without-making-any-persistent-changes-or-executing-transaction..md index 8d83bff159..9206b6b57a 100644 --- a/docs/guardian/standard-registry/policies/tools/tools-apis/run-policy-without-making-any-persistent-changes-or-executing-transaction..md +++ b/docs/guardian/standard-registry/policies/tools/tools-apis/run-policy-without-making-any-persistent-changes-or-executing-transaction..md @@ -1,64 +1,43 @@ -# Run policy without making any persistent changes or executing transaction. +# Run Tool in Dry-Run Mode -`PUT` `/tools/{id}/dry-run` +**`PUT /api/v1/tools/{id}/dry-run`** -Run policy without making any persistent changes or executing\ -transaction. Only users with the Standard Registry role are allowed to\ -make the request. +Runs a tool without making any persistent changes or executing transactions, allowing safe testing of the tool configuration. -**Headers** +**Authentication:** Bearer token required (`Authorization: Bearer `) -| Name | Value | -| ------------- | ------------------ | -| Content-Type | `application/json` | -| Authorization | `Bearer ` | +**Permission:** `Permissions.TOOLS_TOOL_UPDATE` -**Body** +--- -| Name | Type | Description | -| ---- | ------ | ----------- | -| id | string | Tool ID | +## Request -**Response** +### Path Parameters -{% tabs %} -{% tab title="200" %} -```json5 -{ - description: Successful operation. - content: - application/json: - schema: - $ref: '#/components/schemas/ToolValidationDTO' -} -``` -{% endtab %} +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `id` | string | Yes | Tool ID (MongoDB ObjectId) | -{% tab title="401" %} -```json5 -{ - description: Unauthorized. -} -``` -{% endtab %} +--- -{% tab title="403" %} -```json5 -{ -description: Forbidden. -} -``` -{% endtab %} +## Response + +### Success Response -{% tab title="500" %} -```json5 +**Status:** `200 OK` + +```json { -description: Internal server error. - content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' + "valid": true, + "results": [] } ``` -{% endtab %} -{% endtabs %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | `id` is missing or invalid | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/tools/tools-apis/updates-tool-configuration.md b/docs/guardian/standard-registry/policies/tools/tools-apis/updates-tool-configuration.md index 6e37d693d1..2cd717bf84 100644 --- a/docs/guardian/standard-registry/policies/tools/tools-apis/updates-tool-configuration.md +++ b/docs/guardian/standard-registry/policies/tools/tools-apis/updates-tool-configuration.md @@ -1,37 +1,71 @@ # Updates Tool Configuration -{% swagger method="put" path="" baseUrl="/tools/{id}" summary="Updates tool configuration." %} -{% swagger-description %} -Updates tool configuration for the specified tool ID. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`PUT /api/v1/tools/{id}`** -{% swagger-parameter in="path" name="id" type="String" required="true" %} -Tool ID -{% endswagger-parameter %} +Updates the configuration for a specific tool by its ID. -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/ToolDTO' -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.TOOLS_TOOL_UPDATE` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +--- -{% endswagger-response %} +## Request -{% swagger-response status="403: Forbidden" description="Forbidden" %} +### Path Parameters -{% endswagger-response %} +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `id` | string | Yes | Tool ID (MongoDB ObjectId) | -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} +### Request Body + +```json +{ + "name": "Updated Tool Name", + "description": "Updated description", + "config": { + "blockType": "tool", + "children": [] + } +} ``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | Yes | Human-readable name of the tool | +| `description` | string | No | Brief description of the tool's purpose | +| `config` | object | Yes | Tool configuration object; `blockType` must be `"tool"` | + +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "name": "Updated Tool Name", + "description": "Updated description", + "status": "DRAFT", + "creator": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "topicId": "0.0.5000001", + "config": { + "blockType": "tool", + "children": [] + } +} ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | `id` is missing, or tool config is invalid | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/policies/tools/tools-apis/validates-selected-tool.md b/docs/guardian/standard-registry/policies/tools/tools-apis/validates-selected-tool.md index 6011774d9c..c6ca281f8d 100644 --- a/docs/guardian/standard-registry/policies/tools/tools-apis/validates-selected-tool.md +++ b/docs/guardian/standard-registry/policies/tools/tools-apis/validates-selected-tool.md @@ -1,33 +1,60 @@ # Validates Selected Tool -{% swagger method="post" path="" baseUrl="/tools/validate" summary="Validates selected tool." %} -{% swagger-description %} -Validates selected tool. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /api/v1/tools/validate`** -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - type: object -``` -{% endswagger-response %} +Validates the configuration of the provided tool and returns a validation result. + +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +**Permission:** `Permissions.TOOLS_TOOL_UPDATE` or `Permissions.TOOLS_TOOL_REVIEW` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} +## Request -{% endswagger-response %} +### Request Body -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} +```json +{ + "name": "My Tool", + "description": "Tool description", + "config": { + "blockType": "tool", + "children": [] + } +} ``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | Yes | Human-readable name of the tool | +| `description` | string | No | Brief description of the tool's purpose | +| `config` | object | Yes | Tool configuration object to validate | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "valid": true, + "results": [] +} ``` -{% endswagger-response %} -{% endswagger %} + +| Field | Type | Description | +|-------|------|-------------| +| `valid` | boolean | Whether the tool configuration is valid | +| `results` | array | List of validation errors (empty when valid) | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/README.md b/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/README.md index 16c6e69cd1..ecd2f99678 100644 --- a/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/README.md +++ b/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/README.md @@ -1,2 +1,43 @@ -# APIs related to Roles & Permissions +# APIs Related to Roles and Permissions +Guardian uses a role-based access control (RBAC) system. Standard Registry users create custom roles with specific permission sets, then assign those roles to users within their organization. Delegation support also allows ordinary users with the appropriate rights to manage role and policy assignments on behalf of peers. + +**Authentication:** Bearer token required (`Authorization: Bearer `) — obtain via `POST /api/v1/accounts/login`. + +--- + +## Endpoint Index + +| Method | Endpoint | Description | Auth Required | +|--------|----------|-------------|---------------| +| **`GET`** | `/api/v1/permissions` | Returns the full list of available system-level permissions | Yes | +| **`GET`** | `/api/v1/permissions/roles` | Returns a paginated list of roles | Yes | +| **`POST`** | `/api/v1/permissions/roles` | Creates a new custom role | Yes | +| **`PUT`** | `/api/v1/permissions/roles/{id}` | Updates an existing role's configuration | Yes | +| **`DELETE`** | `/api/v1/permissions/roles/{id}` | Deletes a role by ID | Yes | +| **`POST`** | `/api/v1/permissions/roles/default` | Sets a role as the default for new users | Yes | +| **`GET`** | `/api/v1/permissions/users` | Returns a paginated list of manageable users | Yes | +| **`GET`** | `/api/v1/permissions/users/{username}` | Returns a user's roles, permissions, and assigned policies | Yes | +| **`PUT`** | `/api/v1/permissions/users/{username}` | Assigns roles to a user (Standard Registry) | Yes | +| **`GET`** | `/api/v1/permissions/users/{username}/policies` | Returns policies accessible to a user | Yes | +| **`POST`** | `/api/v1/permissions/users/{username}/policies/assign` | Assigns or unassigns policies to a user (Standard Registry) | Yes | +| **`PUT`** | `/api/v1/permissions/users/{username}/delegate` | Delegates roles to a user (ordinary users) | Yes | +| **`POST`** | `/api/v1/permissions/users/{username}/policies/delegate` | Delegates policy access to a user (ordinary users) | Yes | + +--- + +## Endpoints + +- [Returns List of All Permissions](returns-list-of-all-permissions.md) +- [Returns List of All Roles](returns-list-of-all-roles.md) +- [Creates a New Role](creates-a-new-role.md) +- [Updates Role Configuration](updates-role-configuration.md) +- [Deletes Role](deletes-role.md) +- [Setting Default Role](setting-default-role.md) +- [Returns List of All Users](returns-list-of-all-users-for-whom-the-current-user-can-change-the-role.md) +- [Retrieves User Information (Roles, Permissions, Assigned Policies)](retrieves-information-about-the-user-roles-permissions-assigned-policies.md) +- [Updates User Roles (Standard Registry)](updates-user-roles-only-sr.md) +- [Returns List of All Policies for a User](returns-list-of-all-policies.md) +- [Assigns Policies to a User (Standard Registry)](assigns-policies-to-a-user-only-sr.md) +- [Delegates User Roles (Ordinary Users)](updates-user-roles-for-ordinary-uses.md) +- [Delegates Policies to a User (Ordinary Users)](assigns-policies-to-a-user-for-ordinary-users.md) diff --git a/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/assigns-policies-to-a-user-for-ordinary-users.md b/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/assigns-policies-to-a-user-for-ordinary-users.md index c6e0e7e977..95922616ac 100644 --- a/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/assigns-policies-to-a-user-for-ordinary-users.md +++ b/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/assigns-policies-to-a-user-for-ordinary-users.md @@ -1,5 +1,60 @@ -# Assigns policies to a user (for ordinary users) +# Delegates Policies to a User (Ordinary Users) -{% swagger src="../../../../.gitbook/assets/swagger (4) (1).yaml" path="/permissions/users/{username}/policies/delegate" method="post" %} -[swagger (4) (1).yaml](<../../../../.gitbook/assets/swagger (4) (1).yaml>) -{% endswagger %} +**`POST /api/v1/permissions/users/{username}/policies/delegate`** + +Delegates or removes policy access for a user. This endpoint is used by ordinary users with delegation rights. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.DELEGATION_ROLE_MANAGE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `username` | string | Yes | Target user's login name | + +### Request Body + +```json +{ + "policyIds": ["63e3e5e8a01b3c001234abcd"], + "assign": true +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `policyIds` | string[] | Yes | Array of policy IDs to delegate or remove access for | +| `assign` | boolean | Yes | `true` to delegate access, `false` to remove | + +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "name": "Carbon Credits Policy", + "version": "1.0.0", + "status": "PUBLISH", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001" +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | User does not exist or is not a peer under the same Standard Registry | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/assigns-policies-to-a-user-only-sr.md b/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/assigns-policies-to-a-user-only-sr.md index 032ce4ca6c..a7aa02cfe2 100644 --- a/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/assigns-policies-to-a-user-only-sr.md +++ b/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/assigns-policies-to-a-user-only-sr.md @@ -1,5 +1,60 @@ -# Assigns Policies to a User - Only SR +# Assigns Policies to a User (Standard Registry) -{% swagger src="../../../../.gitbook/assets/swagger (4) (1).yaml" path="/permissions/users/{username}/policies/assign" method="post" %} -[swagger (4) (1).yaml](<../../../../.gitbook/assets/swagger (4) (1).yaml>) -{% endswagger %} +**`POST /api/v1/permissions/users/{username}/policies/assign`** + +Assigns or unassigns one or more policies to a specific user. This endpoint is restricted to Standard Registry users. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.PERMISSIONS_ROLE_MANAGE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `username` | string | Yes | Target user's login name | + +### Request Body + +```json +{ + "policyIds": ["63e3e5e8a01b3c001234abcd"], + "assign": true +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `policyIds` | string[] | Yes | Array of policy IDs to assign or unassign | +| `assign` | boolean | Yes | `true` to assign policies, `false` to unassign | + +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "name": "Carbon Credits Policy", + "version": "1.0.0", + "status": "PUBLISH", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001" +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | User does not exist or is not under this Standard Registry | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/creates-a-new-role.md b/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/creates-a-new-role.md index f4feabe247..54ab2ff5c3 100644 --- a/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/creates-a-new-role.md +++ b/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/creates-a-new-role.md @@ -1,5 +1,66 @@ # Creates a New Role -{% swagger src="../../../../.gitbook/assets/swagger (4) (1).yaml" path="/permissions/roles" method="post" %} -[swagger (4) (1).yaml](<../../../../.gitbook/assets/swagger (4) (1).yaml>) -{% endswagger %} +**`POST /api/v1/permissions/roles`** + +Creates a new custom role within the authenticated Standard Registry's organization. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.PERMISSIONS_ROLE_CREATE` + +--- + +## Request + +### Request Body + +```json +{ + "name": "MRV Submitter", + "description": "Can submit MRV data and view approved policies", + "permissions": ["POLICIES_POLICY_READ", "POLICIES_POLICY_EXECUTE"] +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | Yes | Unique role name within the organization | +| `description` | string | No | Human-readable description of the role | +| `permissions` | string[] | Yes | Array of permission names to assign to this role | + +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "name": "MRV Submitter", + "description": "Can submit MRV data and view approved policies", + "permissions": ["POLICIES_POLICY_READ", "POLICIES_POLICY_EXECUTE"], + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "default": false +} +``` + +| Field | Type | Description | +|-------|------|-------------| +| `id` | string | Newly created role identifier | +| `name` | string | Role name | +| `description` | string | Role description | +| `permissions` | string[] | Assigned permission names | +| `owner` | string | DID of the Standard Registry that owns this role | +| `default` | boolean | Whether this is the default role for new users | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Validation error — missing required fields | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/deletes-role.md b/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/deletes-role.md index e56d79e269..bda25d6b15 100644 --- a/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/deletes-role.md +++ b/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/deletes-role.md @@ -1,5 +1,43 @@ # Deletes Role -{% swagger src="../../../../.gitbook/assets/swagger (4) (1).yaml" path="/permissions/roles/{id}" method="delete" %} -[swagger (4) (1).yaml](<../../../../.gitbook/assets/swagger (4) (1).yaml>) -{% endswagger %} +**`DELETE /api/v1/permissions/roles/{id}`** + +Deletes the role with the provided role ID. Users assigned this role will lose the associated permissions. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.PERMISSIONS_ROLE_DELETE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `id` | string | Yes | Role identifier | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true +``` + +Returns `true` when the role was deleted successfully. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Role does not exist | +| `422 Unprocessable Entity` | Invalid or missing role ID | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/retrieves-information-about-the-user-roles-permissions-assigned-policies.md b/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/retrieves-information-about-the-user-roles-permissions-assigned-policies.md index e43fa18b26..555f095f6a 100644 --- a/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/retrieves-information-about-the-user-roles-permissions-assigned-policies.md +++ b/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/retrieves-information-about-the-user-roles-permissions-assigned-policies.md @@ -1,5 +1,60 @@ -# Retrieves information about the user (roles, permissions assigned policies) +# Retrieves User Information (Roles, Permissions, Assigned Policies) -{% swagger src="../../../../.gitbook/assets/swagger (4) (1).yaml" path="/permissions/users/{username}" method="get" %} -[swagger (4) (1).yaml](<../../../../.gitbook/assets/swagger (4) (1).yaml>) -{% endswagger %} +**`GET /api/v1/permissions/users/{username}`** + +Returns permission details, role assignments, and assigned policy information for a specific user. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.PERMISSIONS_ROLE_MANAGE` or `Permissions.DELEGATION_ROLE_MANAGE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `username` | string | Yes | Target user's login name | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "username": "example_user", + "did": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "parent": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "role": "MRV Submitter", + "permissionsGroup": [ + { + "roleId": "63e3e5e8a01b3c001234abcd", + "roleName": "MRV Submitter", + "permissions": ["POLICIES_POLICY_READ", "POLICIES_POLICY_EXECUTE"] + } + ] +} +``` + +| Field | Type | Description | +|-------|------|-------------| +| `username` | string | User's login name | +| `did` | string | User's Hedera DID | +| `parent` | string | Standard Registry DID | +| `role` | string | Currently assigned role name | +| `permissionsGroup` | array | List of role assignments with associated permissions | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | User does not exist or is not under this Standard Registry | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/returns-list-of-all-permissions.md b/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/returns-list-of-all-permissions.md index 09c64d8af1..b133dff38d 100644 --- a/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/returns-list-of-all-permissions.md +++ b/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/returns-list-of-all-permissions.md @@ -1,5 +1,58 @@ -# Returns list of all permissions +# Returns List of All Permissions -{% swagger src="../../../../.gitbook/assets/swagger (4) (1).yaml" path="/permissions" method="get" %} -[swagger (4) (1).yaml](<../../../../.gitbook/assets/swagger (4) (1).yaml>) -{% endswagger %} +**`GET /api/v1/permissions`** + +Returns the full list of available system-level permissions. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.PERMISSIONS_ROLE_READ` or `Permissions.DELEGATION_ROLE_MANAGE` + +--- + +## Request + +No path parameters, query parameters, or request body. + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +[ + { + "name": "POLICIES_POLICY_READ", + "category": "POLICIES", + "entity": "POLICY", + "action": "READ", + "disabled": false + }, + { + "name": "TOKENS_TOKEN_CREATE", + "category": "TOKENS", + "entity": "TOKEN", + "action": "CREATE", + "disabled": false + } +] +``` + +| Field | Type | Description | +|-------|------|-------------| +| `name` | string | Permission identifier (e.g., `POLICIES_POLICY_READ`) | +| `category` | string | Permission category (e.g., `POLICIES`, `TOKENS`) | +| `entity` | string | Target entity (e.g., `POLICY`, `TOKEN`) | +| `action` | string | Allowed action (e.g., `READ`, `CREATE`, `MANAGE`) | +| `disabled` | boolean | Whether the permission is currently disabled | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/returns-list-of-all-policies.md b/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/returns-list-of-all-policies.md index da51f245a7..458d3a1916 100644 --- a/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/returns-list-of-all-policies.md +++ b/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/returns-list-of-all-policies.md @@ -1,5 +1,66 @@ -# Returns list of all Policies +# Returns List of All Policies for a User -{% swagger src="../../../../.gitbook/assets/swagger (4) (1).yaml" path="/permissions/users/{username}/policies" method="get" %} -[swagger (4) (1).yaml](<../../../../.gitbook/assets/swagger (4) (1).yaml>) -{% endswagger %} +**`GET /api/v1/permissions/users/{username}/policies`** + +Returns a paginated list of policies accessible to the specified user. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.PERMISSIONS_ROLE_MANAGE` or `Permissions.DELEGATION_ROLE_MANAGE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `username` | string | Yes | Target user's login name | + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `pageIndex` | number | No | 0 | Zero-based page index | +| `pageSize` | number | No | 20 | Items per page | +| `status` | string | No | — | Filter by policy status (e.g., `DRAFT`, `PUBLISH`, `DISCONTINUED`) | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +The total count of matching policies is returned in the `X-Total-Count` response header. + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "name": "Carbon Credits Policy", + "version": "1.0.0", + "status": "PUBLISH", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001" + } +] +``` + +| Field | Type | Description | +|-------|------|-------------| +| `id` | string | Policy identifier | +| `name` | string | Policy name | +| `version` | string | Policy version | +| `status` | string | Current policy status | +| `owner` | string | DID of the Standard Registry that owns the policy | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | User does not exist or is not under this Standard Registry | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/returns-list-of-all-roles.md b/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/returns-list-of-all-roles.md index 35cffecc3c..0087c7eb11 100644 --- a/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/returns-list-of-all-roles.md +++ b/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/returns-list-of-all-roles.md @@ -1,5 +1,61 @@ -# Returns list of all roles +# Returns List of All Roles -{% swagger src="../../../../.gitbook/assets/swagger (4) (1).yaml" path="/permissions/roles" method="get" %} -[swagger (4) (1).yaml](<../../../../.gitbook/assets/swagger (4) (1).yaml>) -{% endswagger %} +**`GET /api/v1/permissions/roles`** + +Returns a paginated list of roles for the authenticated Standard Registry. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.PERMISSIONS_ROLE_READ` or `Permissions.DELEGATION_ROLE_MANAGE` + +--- + +## Request + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `name` | string | No | — | Filter roles by name | +| `pageIndex` | number | No | 0 | Zero-based page index | +| `pageSize` | number | No | 20 | Items per page | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +The total count of matching roles is returned in the `X-Total-Count` response header. + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "name": "MRV Submitter", + "description": "Can submit MRV data and view policies", + "permissions": ["POLICIES_POLICY_READ", "POLICIES_POLICY_EXECUTE"], + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "default": false + } +] +``` + +| Field | Type | Description | +|-------|------|-------------| +| `id` | string | Role identifier | +| `name` | string | Human-readable role name | +| `description` | string | Role description | +| `permissions` | string[] | List of permission names assigned to this role | +| `owner` | string | DID of the Standard Registry that owns this role | +| `default` | boolean | Whether this is the default role assigned to new users | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/returns-list-of-all-users-for-whom-the-current-user-can-change-the-role.md b/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/returns-list-of-all-users-for-whom-the-current-user-can-change-the-role.md index 635c3330b2..e0af0ffc8a 100644 --- a/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/returns-list-of-all-users-for-whom-the-current-user-can-change-the-role.md +++ b/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/returns-list-of-all-users-for-whom-the-current-user-can-change-the-role.md @@ -1,5 +1,68 @@ -# Returns list of all users for whom the current user can change the role +# Returns List of All Users -{% swagger src="../../../../.gitbook/assets/swagger (4) (1).yaml" path="/permissions/users" method="get" %} -[swagger (4) (1).yaml](<../../../../.gitbook/assets/swagger (4) (1).yaml>) -{% endswagger %} +**`GET /api/v1/permissions/users`** + +Returns a paginated list of users under the authenticated Standard Registry for whom the current user can manage roles. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.PERMISSIONS_ROLE_MANAGE` or `Permissions.DELEGATION_ROLE_MANAGE` + +--- + +## Request + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `role` | string | No | — | Filter by role ID | +| `status` | string | No | — | Filter by status (`Active` or `Inactive`) | +| `username` | string | No | — | Filter by username | +| `pageIndex` | number | No | 0 | Zero-based page index | +| `pageSize` | number | No | 20 | Items per page | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +The total count of matching users is returned in the `X-Total-Count` response header. + +```json +[ + { + "username": "example_user", + "did": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "parent": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "role": "MRV Submitter", + "permissionsGroup": [ + { + "roleId": "63e3e5e8a01b3c001234abcd", + "roleName": "MRV Submitter" + } + ], + "assignedEntities": [] + } +] +``` + +| Field | Type | Description | +|-------|------|-------------| +| `username` | string | User's login name | +| `did` | string | User's Hedera DID | +| `parent` | string | Standard Registry DID | +| `role` | string | Currently assigned role name | +| `permissionsGroup` | array | List of role assignments | +| `assignedEntities` | array | Policies and other entities assigned to this user | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/setting-default-role.md b/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/setting-default-role.md index 9c2fb5bbe7..aecbb2880b 100644 --- a/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/setting-default-role.md +++ b/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/setting-default-role.md @@ -1,5 +1,55 @@ # Setting Default Role -{% swagger src="../../../../.gitbook/assets/swagger (4) (1).yaml" path="/permissions/roles/default" method="post" %} -[swagger (4) (1).yaml](<../../../../.gitbook/assets/swagger (4) (1).yaml>) -{% endswagger %} +**`POST /api/v1/permissions/roles/default`** + +Sets the specified role as the default role that is automatically assigned to new users who join the organization. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.PERMISSIONS_ROLE_CREATE` + +--- + +## Request + +### Request Body + +```json +{ + "id": "63e3e5e8a01b3c001234abcd" +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `id` | string | Yes | ID of the role to set as the default | + +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "name": "MRV Submitter", + "description": "Can submit MRV data and view policies", + "permissions": ["POLICIES_POLICY_READ", "POLICIES_POLICY_EXECUTE"], + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "default": true +} +``` + +Returns the updated role object with `default` set to `true`. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Role does not exist | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/updates-role-configuration.md b/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/updates-role-configuration.md index 3625bfe08f..b331cfa11e 100644 --- a/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/updates-role-configuration.md +++ b/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/updates-role-configuration.md @@ -1,5 +1,63 @@ # Updates Role Configuration -{% swagger src="../../../../.gitbook/assets/swagger (4) (1).yaml" path="/permissions/roles/{id}" method="put" %} -[swagger (4) (1).yaml](<../../../../.gitbook/assets/swagger (4) (1).yaml>) -{% endswagger %} +**`PUT /api/v1/permissions/roles/{id}`** + +Updates the configuration (name, description, or permission set) of an existing role. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.PERMISSIONS_ROLE_UPDATE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `id` | string | Yes | Role identifier | + +### Request Body + +```json +{ + "name": "MRV Submitter", + "description": "Updated description for the MRV Submitter role", + "permissions": ["POLICIES_POLICY_READ", "POLICIES_POLICY_EXECUTE", "TOKENS_TOKEN_READ"] +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | No | Updated role name | +| `description` | string | No | Updated role description | +| `permissions` | string[] | No | Updated list of permission names for this role | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "name": "MRV Submitter", + "description": "Updated description for the MRV Submitter role", + "permissions": ["POLICIES_POLICY_READ", "POLICIES_POLICY_EXECUTE", "TOKENS_TOKEN_READ"], + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "default": false +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Role does not exist | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/updates-user-roles-for-ordinary-uses.md b/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/updates-user-roles-for-ordinary-uses.md index 496ee16639..4b01f63c64 100644 --- a/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/updates-user-roles-for-ordinary-uses.md +++ b/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/updates-user-roles-for-ordinary-uses.md @@ -1,5 +1,66 @@ -# Updates user roles (for ordinary uses) +# Delegates User Roles (Ordinary Users) -{% swagger src="../../../../.gitbook/assets/swagger (4) (1).yaml" path="/permissions/users/{username}/delegate" method="put" %} -[swagger (4) (1).yaml](<../../../../.gitbook/assets/swagger (4) (1).yaml>) -{% endswagger %} +**`PUT /api/v1/permissions/users/{username}/delegate`** + +Delegates role permissions to a user, allowing them to act with the permissions of a delegated role. This endpoint is used by ordinary users with delegation rights. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.DELEGATION_ROLE_MANAGE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `username` | string | Yes | Target user's login name | + +### Request Body + +An array of role IDs to delegate to the user. Pass an empty array to remove all delegations. + +```json +[ + "63e3e5e8a01b3c001234abcd", + "63e3e5e8a01b3c001234efgh" +] +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| *(array item)* | string | Yes | Role ID to delegate to the user | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "username": "example_user", + "did": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "parent": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "role": "MRV Submitter", + "permissionsGroup": [ + { + "roleId": "63e3e5e8a01b3c001234abcd", + "roleName": "MRV Submitter" + } + ] +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | User does not exist or is not a peer under the same Standard Registry | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/updates-user-roles-only-sr.md b/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/updates-user-roles-only-sr.md index 037e1b755b..181514330d 100644 --- a/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/updates-user-roles-only-sr.md +++ b/docs/guardian/standard-registry/roles-and-permissions/apis-related-to-roles-and-permissions/updates-user-roles-only-sr.md @@ -1,5 +1,66 @@ -# Updates User Roles (only SR) +# Updates User Roles (Standard Registry) -{% swagger src="../../../../.gitbook/assets/swagger (4) (1).yaml" path="/permissions/users/{username}" method="put" %} -[swagger (4) (1).yaml](<../../../../.gitbook/assets/swagger (4) (1).yaml>) -{% endswagger %} +**`PUT /api/v1/permissions/users/{username}`** + +Assigns one or more roles to a user. This endpoint is restricted to Standard Registry users. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.PERMISSIONS_ROLE_MANAGE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `username` | string | Yes | Target user's login name | + +### Request Body + +An array of role IDs to assign to the user. + +```json +[ + "63e3e5e8a01b3c001234abcd", + "63e3e5e8a01b3c001234efgh" +] +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| *(array item)* | string | Yes | Role ID to assign to the user | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "username": "example_user", + "did": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "parent": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "role": "MRV Submitter", + "permissionsGroup": [ + { + "roleId": "63e3e5e8a01b3c001234abcd", + "roleName": "MRV Submitter" + } + ] +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | User does not exist or is not under this Standard Registry | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/schemas/schema-apis-for-asynchronous-execution/README.md b/docs/guardian/standard-registry/schemas/schema-apis-for-asynchronous-execution/README.md index 97bf09abfb..669ad08d05 100644 --- a/docs/guardian/standard-registry/schemas/schema-apis-for-asynchronous-execution/README.md +++ b/docs/guardian/standard-registry/schemas/schema-apis-for-asynchronous-execution/README.md @@ -1,2 +1,27 @@ # Schema APIs for Asynchronous Execution +Asynchronous variants of schema operations that return a task ID immediately and complete in the background. Poll `GET /api/v1/tasks/{taskId}` to retrieve results. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `POST` | `/api/v1/schemas/push` | Creates a new schema asynchronously | Yes | +| `POST` | `/api/v1/schemas/push/copy` | Copies a schema asynchronously | Yes | +| `DELETE` | `/api/v1/schemas/push/{schemaId}` | Deletes a schema asynchronously | Yes | +| `PUT` | `/api/v1/schemas/push/{schemaId}/publish` | Publishes a schema asynchronously | Yes | +| `POST` | `/api/v1/schemas/push/import/message` | Imports a schema from IPFS asynchronously | Yes | +| `POST` | `/api/v1/schemas/push/import/file` | Imports a schema from a ZIP file asynchronously | Yes | +| `POST` | `/api/v1/schemas/push/import/message/preview` | Previews a schema from IPFS asynchronously | Yes | + +## Endpoints + +- [Creation of Schema (Async)](creation-of-schema.md) +- [Copy Schema](copy-schema.md) +- [Deletes the Schema with the Provided Schema ID](deletes-the-schema-with-the-provided-schema-id.md) +- [Publishing Schema](publishing-schema.md) +- [Importing Schema from IPFS](importing-schema-from-ipfs.md) +- [Importing Schema from ZIP](importing-schema-from-.zip.md) +- [Previews the Schema from IPFS](previews-the-schema-from-ipfs.md) diff --git a/docs/guardian/standard-registry/schemas/schema-creation-using-apis/README.md b/docs/guardian/standard-registry/schemas/schema-creation-using-apis/README.md index 743fd8ad0b..6e133393fd 100644 --- a/docs/guardian/standard-registry/schemas/schema-creation-using-apis/README.md +++ b/docs/guardian/standard-registry/schemas/schema-creation-using-apis/README.md @@ -1,2 +1,47 @@ -# Schema APIs +# Schema Creation APIs +Endpoints for creating, retrieving, updating, publishing, and deleting schemas in Guardian. Schemas define the structure of verifiable credential documents used in policies. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `GET` | `/api/v1/schemas` | Returns all schemas accessible to the current user | Yes | +| `POST` | `/api/v1/schemas` | Creates a new schema | Yes | +| `PUT` | `/api/v1/schemas/{schemaId}` | Updates a schema | Yes | +| `DELETE` | `/api/v1/schemas/{schemaId}` | Deletes a schema | Yes | +| `PUT` | `/api/v1/schemas/{schemaId}/publish` | Publishes a schema | Yes | +| `POST` | `/api/v1/schemas/import/message` | Imports a schema from an IPFS message ID | Yes | +| `POST` | `/api/v1/schemas/import/file` | Imports a schema from a ZIP file | Yes | +| `POST` | `/api/v1/schemas/import/message/preview` | Previews a schema from an IPFS message ID | Yes | +| `POST` | `/api/v1/schemas/import/file/preview` | Previews a schema from a ZIP file | Yes | +| `GET` | `/api/v1/schemas/{schemaId}/export/message` | Returns the schema IPFS message ID | Yes | +| `GET` | `/api/v1/schemas/{schemaId}/export/file` | Exports a schema as a ZIP file | Yes | +| `GET` | `/api/v1/schemas/{topicId}` | Returns all schemas for the specified topic | Yes | +| `POST` | `/api/v1/schemas/{topicId}` | Creates a schema under the specified topic | Yes | +| `GET` | `/api/v1/schemas/{schemaId}/sub-schemas` | Returns all child schemas | Yes | +| `GET` | `/api/v1/schemas/{schemaId}` | Returns a schema by ID | Yes | +| `GET` | `/api/v1/schemas/{schemaId}/example` | Returns a sample payload for the schema | Yes | +| `DELETE` | `/api/v1/schemas/{topicId}/all` | Deletes all schemas under the topic | Yes | + +## Endpoints + +- [Returns All Schemas](creation-of-a-schema-1.md) +- [Creation of a Schema Related to the Topic](creation-of-schema-related-to-the-topic.md) +- [Updating Schema](updating-schema.md) +- [Deleting a Schema](deleting-a-schema.md) +- [Publishing Schema Based on Schema ID](publishing-schema-based-on-schema-id.md) +- [Importing Schema from IPFS](importing-schema-from-ipfs.md) +- [Importing ZIP File Containing Schema](importing-zip-file-containing-schema.md) +- [Schema Preview from IPFS](schema-preview-from-ipfs.md) +- [Schema Preview from ZIP](schema-preview-from-zip.md) +- [Export a Schema (Message ID)](export-a-schema.md) +- [Export a Schema (File)](export-a-schema-1.md) +- [Returns All Schemas Related to the Topic](returns-all-schemas-related-to-the-topic.md) +- [Returning Schema by Schema ID](returning-schema-by-schemaid.md) +- [Returns All Child Schemas](returns-all-child-schemas.md) +- [Returns a Sample Payload for the Schema](returns-a-sample-payload-for-the-schema-by-schema-id..md) +- [Previews List of Schema Duplicates](previews-list-of-schemas-duplicates.md) +- [Deletes All Schemas by Topic ID](deletes-all-schemas-by-topic-id.-only-users-with-the-standard-registry-are-allowed..md) diff --git a/docs/guardian/standard-registry/schemas/schema-differentiation/schema-differentiation-apis/README.md b/docs/guardian/standard-registry/schemas/schema-differentiation/schema-differentiation-apis/README.md index dd84d18c2c..7970a7eb52 100644 --- a/docs/guardian/standard-registry/schemas/schema-differentiation/schema-differentiation-apis/README.md +++ b/docs/guardian/standard-registry/schemas/schema-differentiation/schema-differentiation-apis/README.md @@ -1,2 +1,17 @@ # Schema Differentiation APIs +Endpoints for comparing two schemas and exporting the comparison results. Useful for reviewing changes between schema versions. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `POST` | `/api/v1/analytics/compare/schemas` | Compares two schemas and returns the differences | Yes | +| `GET` | `/api/v1/analytics/compare/schemas/export` | Exports schema comparison results as a file | Yes | + +## Endpoints + +- [Returns Result of Schema Comparison](returns-result-of-schema-comparison.md) +- [Exports Schema Differentiation Results](exports-schema-differentiation-results.md) diff --git a/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/README.md b/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/README.md index 3cf295d5e8..2f48468450 100644 --- a/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/README.md +++ b/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/README.md @@ -1,6 +1,41 @@ +# APIs Related to Schema Rules + +Schema Rules define validation rule sets applied to schema documents within policies. Rules specify field-level constraints, cross-field dependencies, and data quality checks beyond basic JSON Schema validation. + +**Authentication:** All endpoints require a Bearer JWT token (`Authorization: Bearer `). Obtain a token via `POST /accounts/login`. + --- -icon: webhook + +## Endpoints + +| Method | Endpoint | Description | Auth Required | +|--------|----------|-------------|---------------| +| **`POST`** | `/api/v1/schema-rules` | Creates a new schema rule | Yes | +| **`GET`** | `/api/v1/schema-rules` | Returns a paginated list of all schema rules | Yes | +| **`GET`** | `/api/v1/schema-rules/{ruleId}` | Retrieves a schema rule by ID | Yes | +| **`PUT`** | `/api/v1/schema-rules/{ruleId}` | Updates a schema rule by ID | Yes | +| **`DELETE`** | `/api/v1/schema-rules/{ruleId}` | Deletes a schema rule by ID | Yes | +| **`PUT`** | `/api/v1/schema-rules/{ruleId}/activate` | Activates a schema rule | Yes | +| **`PUT`** | `/api/v1/schema-rules/{ruleId}/inactivate` | Deactivates a schema rule | Yes | +| **`GET`** | `/api/v1/schema-rules/{ruleId}/relationships` | Lists all schemas and policies linked to a rule | Yes | +| **`POST`** | `/api/v1/schema-rules/data` | Retrieves data needed for evaluating rules | Yes | +| **`POST`** | `/api/v1/schema-rules/{policyId}/import/file` | Imports schema rules from a ZIP file | Yes | +| **`GET`** | `/api/v1/schema-rules/{ruleId}/export/file` | Exports a schema rule to a ZIP file | Yes | +| **`POST`** | `/api/v1/schema-rules/import/file/preview` | Previews a schema rule ZIP without saving | Yes | + --- -# APIs related to Schema Rules +## Endpoint Details +- [Creation of a New Schema Rule](creation-of-the-new-schema-rule.md) +- [Retrieve the Schema Rules](retrieve-the-schema-rules.md) +- [Retrieve the Configuration of the Rule by Its ID](retrieve-the-configuration-of-the-rule-by-its-id.md) +- [Update the Configuration of the Rule with the Corresponding ID](update-the-configuration-of-the-rule-with-the-corresponding-id.md) +- [Delete the Rule by Its ID](delete-the-rule-by-its-id.md) +- [Activate the Rule with the Specified ID](activate-the-rule-with-the-specified-id.md) +- [Deactivate the Rule with the Specified ID](deactivate-the-rule-with-the-specified-id.md) +- [List All Schemas and Policies Relevant to the Rule with the Specified ID](list-all-the-schemas-and-policy-relevant-to-the-rule-with-the-specified-id.md) +- [Retrieve All the Data Needed for Evaluating the Rules](retrieve-all-the-data-needed-for-evaluating-the-rules.md) +- [Create a New Rule from the File](create-a-new-rule-from-the-file.md) +- [Export the Selected Rule by ID into the File](export-the-selected-rule-by-id-into-the-file.md) +- [Load the File and Return Its Preview](load-the-file-and-return-its-preview.md) diff --git a/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/activate-the-rule-with-the-specified-id.md b/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/activate-the-rule-with-the-specified-id.md index 77b0ca5671..64b5122bc8 100644 --- a/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/activate-the-rule-with-the-specified-id.md +++ b/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/activate-the-rule-with-the-specified-id.md @@ -1,5 +1,53 @@ -# Activate the rule with the specified ID +# Activate the Rule with the Specified ID -{% swagger src="../../../../../.gitbook/assets/swagger (6).yaml" path="/schema-rules/{ruleId}/activate" method="put" %} -[swagger (6).yaml](<../../../../../.gitbook/assets/swagger (6).yaml>) -{% endswagger %} +**`PUT /api/v1/schema-rules/{ruleId}/activate`** + +Activates the schema rule for the specified rule ID, enabling it to validate documents. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.SCHEMAS_RULE_CREATE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `ruleId` | string | Yes | Schema rule identifier (MongoDB ObjectId) | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "3b4e1c2d-5f6a-7890-abcd-ef1234567890", + "name": "MRV Data Quality Rules", + "description": "Validation rules for MRV schema fields", + "creator": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "policyId": "63e3e5e8a01b3c001234abcd", + "policyTopicId": "0.0.4532001", + "policyInstanceTopicId": "0.0.4532002", + "status": "ACTIVE", + "config": {} +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | No rule exists with the given `ruleId` | +| `422 Unprocessable Entity` | `ruleId` parameter is missing or empty | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/create-a-new-rule-from-the-file.md b/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/create-a-new-rule-from-the-file.md index 991b4678af..3801456847 100644 --- a/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/create-a-new-rule-from-the-file.md +++ b/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/create-a-new-rule-from-the-file.md @@ -1,5 +1,60 @@ -# Create a new rule from the file +# Create a New Rule from the File -{% swagger src="../../../../../.gitbook/assets/swagger (6).yaml" path="/schema-rules/{policyId}/import/file" method="post" %} -[swagger (6).yaml](<../../../../../.gitbook/assets/swagger (6).yaml>) -{% endswagger %} +**`POST /api/v1/schema-rules/{policyId}/import/file`** + +Imports new schema rules from a ZIP file into the local database under the specified policy. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.SCHEMAS_RULE_CREATE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `policyId` | string | Yes | Policy identifier (MongoDB ObjectId) to import rules into | + +### Request Body + +A binary ZIP file containing the schema rule configuration to be imported. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| *(binary body)* | zip | Yes | ZIP file containing the exported schema rule | + +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "3b4e1c2d-5f6a-7890-abcd-ef1234567890", + "name": "MRV Data Quality Rules", + "description": "Validation rules for MRV schema fields", + "creator": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "policyId": "63e3e5e8a01b3c001234abcd", + "policyTopicId": "0.0.4532001", + "policyInstanceTopicId": "0.0.4532002", + "status": "DRAFT", + "config": {} +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | ZIP file is missing or corrupt | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/creation-of-the-new-schema-rule.md b/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/creation-of-the-new-schema-rule.md index 16210389f9..d7ac2dea11 100644 --- a/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/creation-of-the-new-schema-rule.md +++ b/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/creation-of-the-new-schema-rule.md @@ -1,5 +1,71 @@ -# Creation of the new schema rule +# Creation of a New Schema Rule -{% swagger src="../../../../../.gitbook/assets/swagger (6).yaml" path="/schema-rules" method="post" %} -[swagger (6).yaml](<../../../../../.gitbook/assets/swagger (6).yaml>) -{% endswagger %} +**`POST /api/v1/schema-rules`** + +Creates a new schema rule. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.SCHEMAS_RULE_CREATE` + +--- + +## Request + +### Request Body + +```json +{ + "name": "MRV Data Quality Rules", + "description": "Validation rules for MRV schema fields", + "policyId": "63e3e5e8a01b3c001234abcd", + "policyTopicId": "0.0.4532001", + "policyInstanceTopicId": "0.0.4532002", + "config": {} +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | Yes | Human-readable name for the rule | +| `description` | string | No | Optional description of the rule | +| `uuid` | string | No | Rule UUID; auto-generated if omitted | +| `policyId` | string | No | ID of the policy this rule is scoped to | +| `policyTopicId` | string | No | Hedera topic ID of the associated policy | +| `policyInstanceTopicId` | string | No | Hedera topic ID of the policy instance | +| `status` | string | No | Initial status; defaults to `DRAFT` | +| `config` | object | No | Rule configuration (conditions, constraints) | + +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "3b4e1c2d-5f6a-7890-abcd-ef1234567890", + "name": "MRV Data Quality Rules", + "description": "Validation rules for MRV schema fields", + "creator": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "policyId": "63e3e5e8a01b3c001234abcd", + "policyTopicId": "0.0.4532001", + "policyInstanceTopicId": "0.0.4532002", + "status": "DRAFT", + "config": {} +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `400 Bad Request` | Malformed request body | +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Invalid configuration — body is empty or malformed | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/deactivate-the-rule-with-the-specified-id.md b/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/deactivate-the-rule-with-the-specified-id.md index e2367f5913..3f6e1bc9c8 100644 --- a/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/deactivate-the-rule-with-the-specified-id.md +++ b/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/deactivate-the-rule-with-the-specified-id.md @@ -1,5 +1,53 @@ -# Deactivate the rule with the specified ID +# Deactivate the Rule with the Specified ID -{% swagger src="../../../../../.gitbook/assets/swagger (6).yaml" path="/schema-rules/{ruleId}/inactivate" method="put" %} -[swagger (6).yaml](<../../../../../.gitbook/assets/swagger (6).yaml>) -{% endswagger %} +**`PUT /api/v1/schema-rules/{ruleId}/inactivate`** + +Inactivates the schema rule for the specified rule ID without deleting it. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.SCHEMAS_RULE_CREATE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `ruleId` | string | Yes | Schema rule identifier (MongoDB ObjectId) | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "3b4e1c2d-5f6a-7890-abcd-ef1234567890", + "name": "MRV Data Quality Rules", + "description": "Validation rules for MRV schema fields", + "creator": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "policyId": "63e3e5e8a01b3c001234abcd", + "policyTopicId": "0.0.4532001", + "policyInstanceTopicId": "0.0.4532002", + "status": "INACTIVE", + "config": {} +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | No rule exists with the given `ruleId` | +| `422 Unprocessable Entity` | `ruleId` parameter is missing or empty | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/delete-the-rule-by-its-id.md b/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/delete-the-rule-by-its-id.md index b6a1243335..1a9b8b73de 100644 --- a/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/delete-the-rule-by-its-id.md +++ b/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/delete-the-rule-by-its-id.md @@ -1,5 +1,40 @@ -# Delete the rule by its ID +# Delete the Rule by Its ID -{% swagger src="../../../../../.gitbook/assets/swagger (6).yaml" path="/schema-rules/{ruleId}" method="delete" %} -[swagger (6).yaml](<../../../../../.gitbook/assets/swagger (6).yaml>) -{% endswagger %} +**`DELETE /api/v1/schema-rules/{ruleId}`** + +Deletes the schema rule with the specified ID. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.SCHEMAS_RULE_CREATE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `ruleId` | string | Yes | Schema rule identifier (MongoDB ObjectId) | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | `ruleId` parameter is missing or empty | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/export-the-selected-rule-by-id-into-the-file.md b/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/export-the-selected-rule-by-id-into-the-file.md index 5b7e87c06c..55aca2dacf 100644 --- a/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/export-the-selected-rule-by-id-into-the-file.md +++ b/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/export-the-selected-rule-by-id-into-the-file.md @@ -1,5 +1,42 @@ -# Export the selected rule (by ID) into the file +# Export the Selected Rule by ID into the File -{% swagger src="../../../../../.gitbook/assets/swagger (6).yaml" path="/schemas/{schemaId}/export/file" method="get" %} -[swagger (6).yaml](<../../../../../.gitbook/assets/swagger (6).yaml>) -{% endswagger %} +**`GET /api/v1/schema-rules/{ruleId}/export/file`** + +Returns a ZIP file containing the exported schema rule configuration for the specified rule ID. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.SCHEMAS_RULE_READ` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `ruleId` | string | Yes | Schema rule identifier (MongoDB ObjectId) | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +Returns a binary ZIP file as the response body. + +| Header | Value | +|--------|-------| +| `Content-Type` | `application/zip` | +| `Content-Disposition` | `attachment; filename=theme_` | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/list-all-the-schemas-and-policy-relevant-to-the-rule-with-the-specified-id.md b/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/list-all-the-schemas-and-policy-relevant-to-the-rule-with-the-specified-id.md index ff555aeaaf..58b10afca7 100644 --- a/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/list-all-the-schemas-and-policy-relevant-to-the-rule-with-the-specified-id.md +++ b/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/list-all-the-schemas-and-policy-relevant-to-the-rule-with-the-specified-id.md @@ -1,5 +1,55 @@ -# List all the schemas and policy relevant to the rule with the specified ID +# List All Schemas and Policies Relevant to the Rule with the Specified ID -{% swagger src="../../../../../.gitbook/assets/swagger (6).yaml" path="/schema-rules/{ruleId}/relationships" method="get" %} -[swagger (6).yaml](<../../../../../.gitbook/assets/swagger (6).yaml>) -{% endswagger %} +**`GET /api/v1/schema-rules/{ruleId}/relationships`** + +Retrieves the policy and all schemas linked to the specified schema rule. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.SCHEMAS_RULE_READ` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `ruleId` | string | Yes | Schema rule identifier (MongoDB ObjectId) | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "policy": { + "id": "63e3e5e8a01b3c001234abcd", + "name": "Carbon Credit Policy", + "version": "1.0.0", + "status": "PUBLISH" + }, + "schemas": [ + { + "id": "63e3e5e8a01b3c001234abce", + "name": "MRV Schema", + "version": "1.0.0", + "status": "PUBLISHED" + } + ] +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | `ruleId` parameter is missing or empty | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/load-the-file-and-return-its-preview.md b/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/load-the-file-and-return-its-preview.md index 360c199961..9997288f0f 100644 --- a/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/load-the-file-and-return-its-preview.md +++ b/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/load-the-file-and-return-its-preview.md @@ -1,5 +1,54 @@ -# Load the file and return its preview +# Load the File and Return Its Preview -{% swagger src="../../../../../.gitbook/assets/swagger (6).yaml" path="/schema-rules/import/file/preview" method="post" %} -[swagger (6).yaml](<../../../../../.gitbook/assets/swagger (6).yaml>) -{% endswagger %} +**`POST /api/v1/schema-rules/import/file/preview`** + +Imports a ZIP file containing a schema rule and returns a preview of the rule without saving it to the database. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.SCHEMAS_RULE_CREATE` + +--- + +## Request + +### Request Body + +A binary ZIP file previously exported from the schema rules export endpoint. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| *(binary body)* | zip | Yes | ZIP file containing the exported schema rule | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "3b4e1c2d-5f6a-7890-abcd-ef1234567890", + "name": "MRV Data Quality Rules", + "description": "Validation rules for MRV schema fields", + "creator": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "policyId": "63e3e5e8a01b3c001234abcd", + "policyTopicId": "0.0.4532001", + "policyInstanceTopicId": "0.0.4532002", + "status": "DRAFT", + "config": {} +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | ZIP file is missing or corrupt | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/retrieve-all-the-data-needed-for-evaluating-the-rules.md b/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/retrieve-all-the-data-needed-for-evaluating-the-rules.md index 07edf6a2ef..a867f32b3a 100644 --- a/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/retrieve-all-the-data-needed-for-evaluating-the-rules.md +++ b/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/retrieve-all-the-data-needed-for-evaluating-the-rules.md @@ -1,5 +1,70 @@ -# Retrieve all the data needed for evaluating the rules +# Retrieve All the Data Needed for Evaluating the Rules -{% swagger src="../../../../../.gitbook/assets/swagger (6).yaml" path="/schema-rules/data" method="post" %} -[swagger (6).yaml](<../../../../../.gitbook/assets/swagger (6).yaml>) -{% endswagger %} +**`POST /api/v1/schema-rules/data`** + +Returns the schema rules and associated document data required to evaluate rule conditions for a given document. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.SCHEMAS_RULE_EXECUTE` *(returns `null` if the user lacks this permission)* + +--- + +## Request + +### Request Body + +```json +{ + "policyId": "63e3e5e8a01b3c001234abcd", + "schemaId": "63e3e5e8a01b3c001234abce", + "documentId": "63e3e5e8a01b3c001234abcf", + "parentId": "63e3e5e8a01b3c001234abd0" +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `policyId` | string | No | Policy context for rule lookup | +| `schemaId` | string | No | Schema ID to find applicable rules | +| `documentId` | string | No | ID of the document to evaluate | +| `parentId` | string | No | ID of the parent document, if applicable | + +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +```json +[ + { + "rules": { + "id": "63e3e5e8a01b3c001234abcd", + "name": "MRV Data Quality Rules", + "status": "ACTIVE", + "config": {} + }, + "document": { + "id": "63e3e5e8a01b3c001234abcf", + "type": "VerifiableCredential" + }, + "relationships": [ + { + "id": "63e3e5e8a01b3c001234abd0", + "type": "VerifiableCredential" + } + ] + } +] +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `422 Unprocessable Entity` | Request body is empty or malformed | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/retrieve-the-configuration-of-the-rule-by-its-id.md b/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/retrieve-the-configuration-of-the-rule-by-its-id.md index f02e726efe..b9ffc0517b 100644 --- a/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/retrieve-the-configuration-of-the-rule-by-its-id.md +++ b/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/retrieve-the-configuration-of-the-rule-by-its-id.md @@ -1,5 +1,53 @@ -# Retrieve the configuration of the rule by its ID +# Retrieve the Configuration of the Rule by Its ID -{% swagger src="../../../../../.gitbook/assets/swagger (6).yaml" path="/schema-rules/{ruleId}" method="get" %} -[swagger (6).yaml](<../../../../../.gitbook/assets/swagger (6).yaml>) -{% endswagger %} +**`GET /api/v1/schema-rules/{ruleId}`** + +Retrieves the schema rule configuration for the specified rule ID. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.SCHEMAS_RULE_READ` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `ruleId` | string | Yes | Schema rule identifier (MongoDB ObjectId) | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "3b4e1c2d-5f6a-7890-abcd-ef1234567890", + "name": "MRV Data Quality Rules", + "description": "Validation rules for MRV schema fields", + "creator": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "policyId": "63e3e5e8a01b3c001234abcd", + "policyTopicId": "0.0.4532001", + "policyInstanceTopicId": "0.0.4532002", + "status": "ACTIVE", + "config": {} +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | No rule exists with the given `ruleId` | +| `422 Unprocessable Entity` | `ruleId` parameter is missing or empty | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/retrieve-the-schema-rules.md b/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/retrieve-the-schema-rules.md index 29f1d54f95..e0d3e54ead 100644 --- a/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/retrieve-the-schema-rules.md +++ b/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/retrieve-the-schema-rules.md @@ -1,5 +1,57 @@ -# Retrieve the schema rules +# Retrieve the Schema Rules -{% swagger src="../../../../../.gitbook/assets/swagger (6).yaml" path="/schema-rules" method="get" %} -[swagger (6).yaml](<../../../../../.gitbook/assets/swagger (6).yaml>) -{% endswagger %} +**`GET /api/v1/schema-rules`** + +Returns a paginated list of all schema rules visible to the authenticated user. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.SCHEMAS_RULE_READ` + +--- + +## Request + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `pageIndex` | number | No | 0 | Zero-based page index | +| `pageSize` | number | No | 20 | Number of items to return per page | +| `policyInstanceTopicId` | string | No | — | Filter results by Hedera policy instance topic ID | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +The total number of matching rules is returned in the `X-Total-Count` response header. + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "3b4e1c2d-5f6a-7890-abcd-ef1234567890", + "name": "MRV Data Quality Rules", + "description": "Validation rules for MRV schema fields", + "creator": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "policyId": "63e3e5e8a01b3c001234abcd", + "policyTopicId": "0.0.4532001", + "policyInstanceTopicId": "0.0.4532002", + "status": "ACTIVE", + "config": {} + } +] +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/update-the-configuration-of-the-rule-with-the-corresponding-id.md b/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/update-the-configuration-of-the-rule-with-the-corresponding-id.md index 084158b063..63d5394451 100644 --- a/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/update-the-configuration-of-the-rule-with-the-corresponding-id.md +++ b/docs/guardian/standard-registry/schemas/schema-rules/apis-related-to-schema-rules/update-the-configuration-of-the-rule-with-the-corresponding-id.md @@ -1,5 +1,78 @@ -# Update the configuration of the rule with the corresponding ID +# Update the Configuration of the Rule with the Corresponding ID -{% swagger src="../../../../../.gitbook/assets/swagger (6).yaml" path="/schema-rules/{ruleId}" method="put" %} -[swagger (6).yaml](<../../../../../.gitbook/assets/swagger (6).yaml>) -{% endswagger %} +**`PUT /api/v1/schema-rules/{ruleId}`** + +Updates the schema rule configuration for the specified rule ID. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.SCHEMAS_RULE_CREATE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `ruleId` | string | Yes | Schema rule identifier (MongoDB ObjectId) | + +### Request Body + +```json +{ + "name": "MRV Data Quality Rules v2", + "description": "Updated validation rules for MRV schema fields", + "policyId": "63e3e5e8a01b3c001234abcd", + "policyTopicId": "0.0.4532001", + "policyInstanceTopicId": "0.0.4532002", + "status": "DRAFT", + "config": {} +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | Yes | Human-readable name for the rule | +| `description` | string | No | Optional description of the rule | +| `uuid` | string | No | Rule UUID | +| `policyId` | string | No | ID of the policy this rule is scoped to | +| `policyTopicId` | string | No | Hedera topic ID of the associated policy | +| `policyInstanceTopicId` | string | No | Hedera topic ID of the policy instance | +| `status` | string | No | Rule status (`DRAFT`, `ACTIVE`, `INACTIVE`) | +| `config` | object | No | Rule configuration (conditions, constraints) | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "3b4e1c2d-5f6a-7890-abcd-ef1234567890", + "name": "MRV Data Quality Rules v2", + "description": "Updated validation rules for MRV schema fields", + "creator": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "policyId": "63e3e5e8a01b3c001234abcd", + "policyTopicId": "0.0.4532001", + "policyInstanceTopicId": "0.0.4532002", + "status": "DRAFT", + "config": {} +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | No rule exists with the given `ruleId` | +| `422 Unprocessable Entity` | `ruleId` parameter is missing or empty | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/schemas/system-schema-apis/README.md b/docs/guardian/standard-registry/schemas/system-schema-apis/README.md index d52635652e..301f884ab4 100644 --- a/docs/guardian/standard-registry/schemas/system-schema-apis/README.md +++ b/docs/guardian/standard-registry/schemas/system-schema-apis/README.md @@ -1,2 +1,27 @@ # System Schema APIs +Endpoints for managing Guardian system schemas — predefined schema types used internally by the platform. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `GET` | `/api/v1/schemas/system/{username}` | Returns system schemas for the specified user | Yes | +| `POST` | `/api/v1/schemas/system/{username}` | Creates a new system schema | Yes | +| `DELETE` | `/api/v1/schemas/system/{schemaId}` | Deletes a system schema | Yes | +| `PUT` | `/api/v1/schemas/system/{schemaId}` | Updates a system schema | Yes | +| `PUT` | `/api/v1/schemas/system/{schemaId}/active` | Publishes (activates) a system schema | Yes | +| `GET` | `/api/v1/schemas/system/entity/{schemaType}` | Returns a system schema by type | Yes | + +## Endpoints + +- [Returns Schema by Username](returns-schema-by-username.md) +- [Creates New System Schema](creates-new-system-schema.md) +- [Delete System Schema](delete-system-schema.md) +- [Updates the Schema](updates-the-schema.md) +- [Publishes the Schema](publishes-the-schema.md) +- [Returns Schema by Type](returns-schema-by-type.md) +- [Schema Type](schema-type.md) +- [Returns Map API Key](returns-map-api-key.md) diff --git a/docs/guardian/standard-registry/schemas/tag-schema/schema-tags-apis/README.md b/docs/guardian/standard-registry/schemas/tag-schema/schema-tags-apis/README.md index 7d77220cef..126a87161f 100644 --- a/docs/guardian/standard-registry/schemas/tag-schema/schema-tags-apis/README.md +++ b/docs/guardian/standard-registry/schemas/tag-schema/schema-tags-apis/README.md @@ -1,2 +1,25 @@ # Schema Tags APIs +Endpoints for creating, updating, and managing tag schemas — schemas associated with tagging entities in Guardian policies. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `GET` | `/api/v1/tags/schemas` | Returns all tag schemas | Yes | +| `POST` | `/api/v1/tags/schemas` | Creates a new tag schema | Yes | +| `PUT` | `/api/v1/tags/schemas/{schemaId}` | Updates a tag schema | Yes | +| `DELETE` | `/api/v1/tags/schemas/{schemaId}` | Deletes a tag schema | Yes | +| `PUT` | `/api/v1/tags/schemas/{schemaId}/publish` | Publishes a tag schema | Yes | +| `GET` | `/api/v1/tags/schemas/published` | Returns all published tag schemas | Yes | + +## Endpoints + +- [Returning All Schema Tags](returning-all-schema-tags.md) +- [Creating New Schema Tag](creating-new-schema-tag.md) +- [Updating Schema Tag](updating-schema-tag.md) +- [Deleting Schema Tag](deleting-schema-tag.md) +- [Publishing Schema](publishing-schema.md) +- [Returning List of Published Schemas](returning-list-of-published-schemas.md) diff --git a/docs/guardian/standard-registry/standard-registry-operations/logs-apis/README.md b/docs/guardian/standard-registry/standard-registry-operations/logs-apis/README.md index e6caa647a2..b844c9a428 100644 --- a/docs/guardian/standard-registry/standard-registry-operations/logs-apis/README.md +++ b/docs/guardian/standard-registry/standard-registry-operations/logs-apis/README.md @@ -1,2 +1,19 @@ # Logs APIs +Endpoints for retrieving Guardian system logs and log attribute metadata for diagnostic and audit purposes. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** Standard Registry role required. + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `POST` | `/api/v1/logs` | Returns filtered system logs | Yes | +| `GET` | `/api/v1/logs/attributes` | Returns all distinct log attribute keys | Yes | + +## Endpoints + +- [Returning Logs](returning-logs.md) +- [Returning Log Attributes](returning-log-attributes.md) diff --git a/docs/guardian/standard-registry/standard-registry-operations/settings-apis/README.md b/docs/guardian/standard-registry/standard-registry-operations/settings-apis/README.md index 199026b161..19f3f9416c 100644 --- a/docs/guardian/standard-registry/standard-registry-operations/settings-apis/README.md +++ b/docs/guardian/standard-registry/standard-registry-operations/settings-apis/README.md @@ -1,2 +1,45 @@ # Settings APIs +Endpoints for retrieving and updating Guardian system settings, such as Hedera operator credentials and IPFS configuration. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** Standard Registry role required. + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `GET` | `/api/v1/settings` | Returns the current Guardian system settings | Yes | +| `POST` | `/api/v1/settings` | Updates the Guardian system settings | Yes | + +## Endpoints + +- [Displaying Current Settings](displaying-current-settings.md) +- [Adding Settings](adding-settings.md) + +--- + +## Branding + +Endpoints for updating and retrieving the platform branding configuration. + +| Method | Endpoint | Description | Auth Required | +|--------|----------|-------------|---------------| +| `POST` | `/api/v1/branding` | Updates the platform branding configuration | Yes | +| `GET` | `/api/v1/branding` | Returns the current platform branding configuration | No | + +--- + +## IPFS File Operations + +Endpoints for uploading, retrieving, and deleting files on IPFS. + +| Method | Endpoint | Description | Auth Required | +|--------|----------|-------------|---------------| +| `POST` | `/api/v1/ipfs/file` | Uploads a file to IPFS | Yes | +| `POST` | `/api/v1/ipfs/file/direct` | Uploads raw JSON data directly to IPFS | Yes | +| `POST` | `/api/v1/ipfs/file/dry-run/{policyId}` | Uploads a file to IPFS in dry-run mode | Yes | +| `GET` | `/api/v1/ipfs/file/{cid}` | Retrieves a file from IPFS by its CID | Yes | +| `GET` | `/api/v1/ipfs/file/{cid}/dry-run` | Retrieves a file from IPFS in dry-run mode | Yes | +| `DELETE` | `/api/v1/ipfs/file/{cid}` | Removes (unpins) a file from IPFS | Yes | diff --git a/docs/guardian/standard-registry/standard-registry-operations/task-statuses-apis/README.md b/docs/guardian/standard-registry/standard-registry-operations/task-statuses-apis/README.md index 6b473aa201..1c00b84ff5 100644 --- a/docs/guardian/standard-registry/standard-registry-operations/task-statuses-apis/README.md +++ b/docs/guardian/standard-registry/standard-registry-operations/task-statuses-apis/README.md @@ -1,2 +1,15 @@ # Task Statuses APIs +Endpoint for polling the status of long-running asynchronous operations. All `push/` endpoints return a `taskId` that can be polled here. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `GET` | `/api/v1/tasks/{taskId}` | Returns the current status and result of an asynchronous task | Yes | + +## Endpoints + +- [Returning Task Statuses](returning-task-statuses.md) diff --git a/docs/guardian/standard-registry/trustchain/trustchain-apis/README.md b/docs/guardian/standard-registry/trustchain/trustchain-apis/README.md index e27ba61f89..704b1631d0 100644 --- a/docs/guardian/standard-registry/trustchain/trustchain-apis/README.md +++ b/docs/guardian/standard-registry/trustchain/trustchain-apis/README.md @@ -1,2 +1,17 @@ -# TrustChain APIs +# Trustchain APIs +Endpoints for building and retrieving the trust chain for a Guardian verifiable presentation (VP) document. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `GET` | `/api/v1/trust-chains/{hash}` | Builds and returns the full trust chain for the specified VP hash | Yes | +| `GET` | `/api/v1/trust-chains` | Returns a paginated list of trust chains | Yes | + +## Endpoints + +- [Building and Returning Trustchain](building-and-returning.md) +- [Requesting Trustchain](requesting.md) diff --git a/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/README.md b/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/README.md index ce233b0cef..1be7cbae63 100644 --- a/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/README.md +++ b/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/README.md @@ -1,2 +1,35 @@ -# APIs related to Statistics +# Policy Statistics APIs +The Policy Statistics APIs allow Standard Registries to create, manage, and evaluate statistic definitions — configurable rule sets that assess and score VC documents produced by Guardian policies. Assessments can be created against a definition and their full relationship graphs retrieved for audit and reporting purposes. + +**Authentication:** All endpoints require a Bearer token (`Authorization: Bearer `), obtained via `POST /accounts/login`. + +| Method | Endpoint | Description | Auth Required | +|--------|----------|-------------|---------------| +| **`POST`** | `/api/v1/policy-statistics` | Creates a new statistic definition | Yes | +| **`GET`** | `/api/v1/policy-statistics` | Returns all statistic definitions | Yes | +| **`GET`** | `/api/v1/policy-statistics/{definitionId}` | Returns a statistic definition by ID | Yes | +| **`PUT`** | `/api/v1/policy-statistics/{definitionId}` | Updates a statistic definition | Yes | +| **`DELETE`** | `/api/v1/policy-statistics/{definitionId}` | Deletes a statistic definition | Yes | +| **`PUT`** | `/api/v1/policy-statistics/{definitionId}/publish` | Publishes a statistic definition | Yes | +| **`GET`** | `/api/v1/policy-statistics/{definitionId}/relationships` | Returns statistic definition relationships | Yes | +| **`GET`** | `/api/v1/policy-statistics/{definitionId}/documents` | Returns all documents for a definition | Yes | +| **`POST`** | `/api/v1/policy-statistics/{definitionId}/assessment` | Creates a new statistic assessment | Yes | +| **`GET`** | `/api/v1/policy-statistics/{definitionId}/assessment` | Returns all assessments for a definition | Yes | +| **`GET`** | `/api/v1/policy-statistics/{definitionId}/assessment/{assessmentId}` | Returns a statistic assessment by ID | Yes | +| **`GET`** | `/api/v1/policy-statistics/{definitionId}/assessment/{assessmentId}/relationships` | Returns assessment relationships | Yes | +| **`POST`** | `/api/v1/policy-statistics/{policyId}/import/file` | Imports a statistic definition from a zip file | Yes | +| **`GET`** | `/api/v1/policy-statistics/{definitionId}/export/file` | Exports a statistic definition as a zip file | Yes | +| **`POST`** | `/api/v1/policy-statistics/import/file/preview` | Previews a statistic definition zip before import | Yes | + +## Endpoints + +- [Returns All Statistic Definitions](returns-all-dashboards.md) +- [Returns All Statistic Assessments](returns-all-reports.md) +- [Returns Statistic Definition by ID](returns-dashboard-by-uuid.md) +- [Returns Statistic Assessment by ID](returns-report-data-by-report-uuid.md) +- [Returns Statistic Definition Relationships](returns-the-status-of-the-current-report.md) +- [Updates Statistic Definition](update-current-report.md) +- [Export Statistic Definition as ZIP File](export-report-data-in-a-csv-file-format.md) +- [Import Statistic Definition from ZIP File](export-report-data-in-a-xlsx-file-format.md) +- [Returns All Documents for a Statistic Definition](returns-metrics.md) diff --git a/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/export-report-data-in-a-csv-file-format.md b/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/export-report-data-in-a-csv-file-format.md index db1ca209ff..96b2ebaddc 100644 --- a/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/export-report-data-in-a-csv-file-format.md +++ b/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/export-report-data-in-a-csv-file-format.md @@ -1,30 +1,43 @@ -# Export report data in a csv file format +# Export Statistic Definition as ZIP File -{% swagger method="get" path="" baseUrl="/analytics/reports/{uuid}/export/csv" summary="Export report data in a csv file format" %} -{% swagger-description %} -Returns a csv file -{% endswagger-description %} +**`GET /api/v1/policy-statistics/{definitionId}/export/file`** -{% swagger-parameter in="path" name="uuid" type="String" required="true" %} -Report Identifier -{% endswagger-parameter %} +Returns a zip file containing the full statistic definition configuration for backup or transfer. -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - type: string - format: binary -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.STATISTICS_STATISTIC_READ` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `definitionId` | string | Yes | Statistic definition identifier | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +The response is a binary zip archive. The `Content-Type` is `application/zip` and the `Content-Disposition` header indicates the filename. -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} ``` -content: - application/json: - schema: - "$ref": "#/components/schemas/InternalServerErrorDTO" +Content-Disposition: attachment; filename=theme_1704067200000 +Content-Type: application/zip ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Invalid or missing `definitionId` | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/export-report-data-in-a-xlsx-file-format.md b/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/export-report-data-in-a-xlsx-file-format.md index 13b1240d94..856d1a0c48 100644 --- a/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/export-report-data-in-a-xlsx-file-format.md +++ b/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/export-report-data-in-a-xlsx-file-format.md @@ -1,30 +1,57 @@ -# Export report data in a xlsx file format +# Import Statistic Definition from ZIP File -{% swagger method="get" path="" baseUrl="/analytics/reports/{uuid}/export/xlsx" summary="Export report data in a xlsx file format." %} -{% swagger-description %} -Returns a .xlsx file -{% endswagger-description %} +**`POST /api/v1/policy-statistics/{policyId}/import/file`** -{% swagger-parameter in="path" name="uuid" type="String" required="true" %} -Report Identifier -{% endswagger-parameter %} +Imports a new statistic definition from the provided zip file and associates it with the specified policy. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.STATISTICS_STATISTIC_CREATE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `policyId` | string | Yes | Policy identifier to associate with the imported definition | + +### Request Body + +The request body must be a binary zip file previously exported via `GET /policy-statistics/{definitionId}/export/file`. -{% swagger-response status="200: OK" description="Successful Operation" %} ``` -content: - application/json: - schema: - type: string - format: binary +Content-Type: application/zip ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` - content: - application/json: - schema: - "$ref": "#/components/schemas/InternalServerErrorDTO" +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "name": "Imported Statistics Definition", + "description": "Imported from zip file", + "status": "DRAFT", + "policyId": "63e3e5e8a01b3c001234aaaa", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "createDate": "2026-04-07T09:00:00.000Z", + "updateDate": "2026-04-07T09:00:00.000Z" +} ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Invalid or missing `policyId` | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/returns-all-dashboards.md b/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/returns-all-dashboards.md index d0a1fadfcf..c736517ade 100644 --- a/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/returns-all-dashboards.md +++ b/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/returns-all-dashboards.md @@ -1,27 +1,54 @@ -# Returns all dashboards +# Returns All Statistic Definitions -{% swagger method="get" path="" baseUrl="/analytics/dashboards" summary="Returns all dashboards." %} -{% swagger-description %} -Returns all dashboards. -{% endswagger-description %} +**`GET /api/v1/policy-statistics`** -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - type: array - items: - "$ref": "#/components/schemas/DashboardDTO" -``` -{% endswagger-response %} +Returns a paginated list of all statistic definitions visible to the authenticated user. -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - "$ref": "#/components/schemas/InternalServerErrorDTO" +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.STATISTICS_STATISTIC_READ` + +--- + +## Request + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `pageIndex` | number | No | 0 | Zero-based page index | +| `pageSize` | number | No | 20 | Items per page | +| `policyInstanceTopicId` | string | No | — | Filter by policy instance topic ID | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +The `X-Total-Count` response header contains the total number of matching records. + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "name": "Carbon Credit Issuance Statistics", + "description": "Tracks issuance metrics for carbon credit policies", + "status": "PUBLISHED", + "policyId": "63e3e5e8a01b3c001234aaaa", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "createDate": "2026-01-15T10:00:00.000Z", + "updateDate": "2026-01-15T12:00:00.000Z" + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/returns-all-reports.md b/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/returns-all-reports.md index b0309ed777..f65142ef17 100644 --- a/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/returns-all-reports.md +++ b/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/returns-all-reports.md @@ -1,27 +1,57 @@ -# Returns all reports +# Returns All Statistic Assessments -{% swagger method="get" path="" baseUrl="/analytics/reports" summary="Returns all reports" %} -{% swagger-description %} -Returns all reports -{% endswagger-description %} +**`GET /api/v1/policy-statistics/{definitionId}/assessment`** -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - type: array - items: - "$ref": "#/components/schemas/ReportDTO" -``` -{% endswagger-response %} +Returns a paginated list of all assessments for the specified statistic definition. -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - "$ref": "#/components/schemas/InternalServerErrorDTO" +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.STATISTICS_STATISTIC_READ` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `definitionId` | string | Yes | Statistic definition identifier | + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `pageIndex` | number | No | 0 | Zero-based page index | +| `pageSize` | number | No | 20 | Items per page | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +The `X-Total-Count` response header contains the total number of matching records. + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "definitionId": "63e3e5e8a01b3c001234aaaa", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "createDate": "2026-01-15T10:00:00.000Z", + "updateDate": "2026-01-15T12:00:00.000Z" + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Invalid or missing `definitionId` | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/returns-dashboard-by-uuid.md b/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/returns-dashboard-by-uuid.md index 3757dea877..1d4d003fc6 100644 --- a/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/returns-dashboard-by-uuid.md +++ b/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/returns-dashboard-by-uuid.md @@ -1,29 +1,49 @@ -# Returns dashboard by uuid +# Returns Statistic Definition by ID -{% swagger method="get" path="" baseUrl="/analytics/dashboards/{id}" summary="Returns dashboard by uuid" %} -{% swagger-description %} -Returns dashboard by uuid -{% endswagger-description %} +**`GET /api/v1/policy-statistics/{definitionId}`** -{% swagger-parameter in="path" name="id" type="String" required="true" %} -Dashboard Identifier -{% endswagger-parameter %} +Retrieves the statistic definition for the specified identifier. -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - "$ref": "#/components/schemas/DataContainerDTO" -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - "$ref": "#/components/schemas/InternalServerErrorDTO" +**Permission:** `Permissions.STATISTICS_STATISTIC_READ` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `definitionId` | string | Yes | Statistic definition identifier | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "name": "Carbon Credit Issuance Statistics", + "description": "Tracks issuance metrics for carbon credit policies", + "status": "PUBLISHED", + "policyId": "63e3e5e8a01b3c001234aaaa", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "createDate": "2026-01-15T10:00:00.000Z", + "updateDate": "2026-01-15T12:00:00.000Z" +} ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Invalid or missing `definitionId` | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/returns-metrics.md b/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/returns-metrics.md index 2ef84af95f..724122e8c1 100644 --- a/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/returns-metrics.md +++ b/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/returns-metrics.md @@ -1,11 +1,63 @@ -# Returns Metrics +# Returns All Documents for a Statistic Definition -{% swagger method="get" path="" baseUrl="/metrics" summary="Returns Metrics" %} -{% swagger-description %} -Returns Metrics -{% endswagger-description %} +**`GET /api/v1/policy-statistics/{definitionId}/documents`** -{% swagger-response status="200: OK" description="Successful Operation" %} +Returns a paginated list of all VC documents that match the criteria of the specified statistic definition. -{% endswagger-response %} -{% endswagger %} +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.STATISTICS_STATISTIC_READ` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `definitionId` | string | Yes | Statistic definition identifier | + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `pageIndex` | number | No | 0 | Zero-based page index | +| `pageSize` | number | No | 20 | Items per page | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +The `X-Total-Count` response header contains the total number of matching records. + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "type": "VC", + "schema": "63e3e5e8a01b3c001234bbbb", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "document": { + "@context": ["https://www.w3.org/2018/credentials/v1"], + "type": ["VerifiableCredential"], + "issuer": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "credentialSubject": {} + }, + "createDate": "2026-01-15T10:00:00.000Z", + "updateDate": "2026-01-15T12:00:00.000Z" + } +] +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/returns-report-data-by-report-uuid.md b/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/returns-report-data-by-report-uuid.md index a4017bee51..80ca948246 100644 --- a/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/returns-report-data-by-report-uuid.md +++ b/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/returns-report-data-by-report-uuid.md @@ -1,28 +1,47 @@ -# Returns report data by report uuid - -{% swagger method="get" path="" baseUrl="/analytics/reports/{uuid}" summary="Returns report data by report uuid" %} -{% swagger-description %} -Returns report data by report uuid -{% endswagger-description %} - -{% swagger-parameter in="path" name="uuid" required="true" type="String" %} -Report Identifier -{% endswagger-parameter %} - -{% swagger-response status="200: OK" description="Successful Operation" %} -
content:
-            application/json:
-              schema:
-                "$ref": "#/components/schemas/DataContainerDTO"
-
-{% endswagger-response %} - -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` - content: - application/json: - schema: - "$ref": "#/components/schemas/InternalServerErrorDTO" +# Returns Statistic Assessment by ID + +**`GET /api/v1/policy-statistics/{definitionId}/assessment/{assessmentId}`** + +Retrieves the statistic assessment for the specified definition and assessment identifiers. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.STATISTICS_STATISTIC_READ` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `definitionId` | string | Yes | Statistic definition identifier | +| `assessmentId` | string | Yes | Statistic assessment identifier | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "definitionId": "63e3e5e8a01b3c001234aaaa", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "createDate": "2026-01-15T10:00:00.000Z", + "updateDate": "2026-01-15T12:00:00.000Z" +} ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Invalid or missing `definitionId` or `assessmentId` | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/returns-the-status-of-the-current-report.md b/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/returns-the-status-of-the-current-report.md index a3a9450bf4..5055402539 100644 --- a/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/returns-the-status-of-the-current-report.md +++ b/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/returns-the-status-of-the-current-report.md @@ -1,25 +1,53 @@ -# Returns the status of the current report +# Returns Statistic Definition Relationships -{% swagger method="get" path="" baseUrl="/analytics/report" summary="Returns the status of the current report" %} -{% swagger-description %} -Returns the status of the current report -{% endswagger-description %} +**`GET /api/v1/policy-statistics/{definitionId}/relationships`** -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - "$ref": "#/components/schemas/ReportDTO" -``` -{% endswagger-response %} +Retrieves the relationship graph for the specified statistic definition, including linked policies, schemas, and documents. -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - "$ref": "#/components/schemas/InternalServerErrorDTO" +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.STATISTICS_STATISTIC_READ` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `definitionId` | string | Yes | Statistic definition identifier | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "name": "Carbon Credit Issuance Statistics", + "policy": { + "id": "63e3e5e8a01b3c001234aaaa", + "name": "Carbon Credit Policy" + }, + "schemas": [ + { + "id": "63e3e5e8a01b3c001234bbbb", + "name": "Emission Reduction Schema" + } + ] +} ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Invalid or missing `definitionId` | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/update-current-report.md b/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/update-current-report.md index 64f9ba8291..38943130be 100644 --- a/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/update-current-report.md +++ b/docs/guardian/standard-registry/usage-statistics/apis-related-to-statistics/update-current-report.md @@ -1,25 +1,69 @@ -# Update current report +# Updates Statistic Definition -{% swagger method="get" path="" baseUrl="/analytics/report/update" summary="Update current report" %} -{% swagger-description %} -Update current report -{% endswagger-description %} +**`PUT /api/v1/policy-statistics/{definitionId}`** -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - "$ref": "#/components/schemas/ReportDTO" -``` -{% endswagger-response %} +Updates the configuration of the statistic definition with the specified identifier. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.STATISTICS_STATISTIC_CREATE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `definitionId` | string | Yes | Statistic definition identifier | + +### Request Body -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} +```json +{ + "name": "Updated Statistics Name", + "description": "Updated description for the statistic definition", + "config": { + "variables": [], + "scores": [] + } +} ``` -content: - application/json: - schema: - "$ref": "#/components/schemas/InternalServerErrorDTO" + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | No | Human-readable name for the definition | +| `description` | string | No | Description of the definition | +| `config` | object | No | Definition configuration object | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "name": "Updated Statistics Name", + "description": "Updated description for the statistic definition", + "status": "DRAFT", + "policyId": "63e3e5e8a01b3c001234aaaa", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "createDate": "2026-01-15T10:00:00.000Z", + "updateDate": "2026-04-07T09:00:00.000Z" +} ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Statistic definition does not exist | +| `422 Unprocessable Entity` | Invalid or missing `definitionId` | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/README.md b/docs/guardian/tokens/retirement-contract/retirement-apis/README.md index 9f6f9140b7..d3f9509789 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/README.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/README.md @@ -1,2 +1,78 @@ -# Retirement APIs +# Retirement Contract APIs +Endpoints for creating and managing Guardian retirement contracts, retire pools, wipe requests, and associated administrators. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `GET` | `/api/v1/contracts` | Returns all retirement contracts | Yes | +| `POST` | `/api/v1/contracts` | Creates a new retirement contract | Yes | +| `POST` | `/api/v1/contracts/import` | Imports an existing retirement contract | Yes | +| `DELETE` | `/api/v1/contracts/{contractId}` | Removes a retirement contract | Yes | +| `GET` | `/api/v1/contracts/{contractId}/permissions` | Returns permissions for the contract | Yes | +| `POST` | `/api/v1/contracts/retire/{contractId}/admin/{hederaId}` | Adds a retire administrator | Yes | +| `DELETE` | `/api/v1/contracts/retire/{contractId}/admin/{hederaId}` | Removes a retire administrator | Yes | +| `GET` | `/api/v1/contracts/retire/pools` | Returns all retire pools | Yes | +| `POST` | `/api/v1/contracts/retire/pools` | Sets retire pools | Yes | +| `DELETE` | `/api/v1/contracts/retire/pools` | Deletes retire pools | Yes | +| `DELETE` | `/api/v1/contracts/retire/pools/{poolId}` | Unsets a retire pool | Yes | +| `POST` | `/api/v1/contracts/retire/pools/sync` | Synchronizes retire pools | Yes | +| `GET` | `/api/v1/contracts/retire/requests` | Returns all retire requests | Yes | +| `DELETE` | `/api/v1/contracts/retire/requests` | Deletes all retire requests | Yes | +| `POST` | `/api/v1/contracts/retire/requests/{requestId}/approve` | Approves a retire request | Yes | +| `DELETE` | `/api/v1/contracts/retire/requests/{requestId}` | Cancels a retire request | Yes | +| `POST` | `/api/v1/contracts/retire` | Retires tokens | Yes | +| `GET` | `/api/v1/contracts/retire` | Returns all retired VCs | Yes | +| `GET` | `/api/v1/contracts/wipe/requests` | Returns all wipe requests | Yes | +| `POST` | `/api/v1/contracts/wipe/requests/{requestId}/approve` | Approves wipe requests | Yes | +| `DELETE` | `/api/v1/contracts/wipe/requests` | Clears wipe requests | Yes | +| `DELETE` | `/api/v1/contracts/wipe/requests/{requestId}` | Rejects wipe requests | Yes | +| `POST` | `/api/v1/contracts/{contractId}/wipe/admin/{hederaId}` | Adds a wipe administrator | Yes | +| `DELETE` | `/api/v1/contracts/{contractId}/wipe/admin/{hederaId}` | Removes a wipe administrator | Yes | +| `POST` | `/api/v1/contracts/{contractId}/wipe/manager/{hederaId}` | Adds a wipe manager | Yes | +| `DELETE` | `/api/v1/contracts/{contractId}/wipe/manager/{hederaId}` | Removes a wipe manager | Yes | +| `POST` | `/api/v1/contracts/{contractId}/wipe/wiper/{hederaId}` | Adds a wipe wiper | Yes | +| `DELETE` | `/api/v1/contracts/{contractId}/wipe/wiper/{hederaId}` | Removes a wipe wiper | Yes | +| `POST` | `/api/v1/contracts/{contractId}/wipe/requests/enable` | Enables wipe requests | Yes | +| `POST` | `/api/v1/contracts/{contractId}/wipe/requests/disable` | Disables wipe requests | Yes | + +## Endpoints + +- [Returns All Contracts](returns-all-contracts.md) +- [Creating New Contract](creating-new-contract.md) +- [Importing New Contract](importing-new-contract.md) +- [Removing Contract](removing-contract.md) +- [Get Contract Permissions](get-contract-permissions.md) +- [Adding Retire Admin](adding-retire-admin.md) +- [Removing Retire Admin](removing-retire-admin.md) +- [Returning List of All Retire Pools](returning-list-of-all-retire-pools.md) +- [Setting Retire Pools](setting-retire-pools.md) +- [Deleting Retire Pools](deleting-retire-pools.md) +- [Unsetting Retire Pool](unsetting-retire-pool.md) +- [Syncing Retire Pools](syncing-retire-pools.md) +- [Returning List of All Retire Requests](returning-list-of-all-retire-requests.md) +- [Deleting Retire Requests](deleting-retire-requests.md) +- [Approving Retire Request](approving-retire-request.md) +- [Cancelling Retire Request](cancelling-retire-request.md) +- [Retiring Tokens](retiring-tokens.md) +- [Returning All Retired VCs](returning-all-retired-vcs.md) +- [Returns a List of All Wipe Requests](returns-a-list-of-all-wipe-requests.md) +- [Approving Wipe Requests](approving-wipe-requests.md) +- [Clearing Wipe Requests](clearing-wipe-requests.md) +- [Rejecting Wipe Requests](rejecting-wipe-requests.md) +- [Adding Wipe Admin](adding-wipe-admin.md) +- [Removing Wipe Admin](removing-wipe-admin.md) +- [Adding Wipe Manager](adding-wipe-manager.md) +- [Removing Wipe Manager](removing-wipe-manager.md) +- [Adding Wipe Wiper](adding-wipe-wiper.md) +- [Removing Wipe Wiper](removing-wipe-wiper.md) +- [Enabling Wipe Requests](enabling-wipe-requests.md) +- [Disabling Wipe Requests](disabling-wipe-requests.md) +- [Adding Wipe for Specific Token](adding-wipe-for-specific-token.md) +- [Deleting Wipe Request for Hedera Account](deleting-wipe-request-for-hedera-account.md) +- [Get Retirement VCs from Indexer](get-retirement-vcs-from-indexer.md) +- [Remove Wipe Request for Specific Token](remove-wipe-request-for-specific-token.md) +- [Unsetting Retire Request](unsetting-retire-request.md) diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/adding-retire-admin.md b/docs/guardian/tokens/retirement-contract/retirement-apis/adding-retire-admin.md index c1f422b6ee..1ea82b0af9 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/adding-retire-admin.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/adding-retire-admin.md @@ -1,36 +1,40 @@ # Adding Retire Admin -{% swagger method="post" path="" baseUrl="/contracts/retire/{contractId}/admin/{hederaId}" summary="Add retire admin." %} -{% swagger-description %} -Add retire contract admin. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /api/v1/contracts/retire/{contractId}/admin/{hederaId}`** -{% swagger-parameter in="path" name="hederaId" type="String" required="true" %} -Hedera Identifier -{% endswagger-parameter %} +Adds a retire contract admin for the specified Hedera account. Only Standard Registry users are allowed to make this request. -{% swagger-parameter in="path" name="contractId" type="String" required="true" %} -Contract Identifier -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} +**Permission:** `Permissions.CONTRACTS_RETIRE_ADMIN_CREATE` -{% endswagger-response %} +--- -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +## Request -{% endswagger-response %} +### Path Parameters -{% swagger-response status="403: Forbidden" description="Forbidden" %} +| Parameter | Type | Required | Description | +|--------------|--------|----------|--------------------------------------------| +| `contractId` | string | Yes | Contract identifier | +| `hederaId` | string | Yes | Hedera account ID to grant admin rights to | -{% endswagger-response %} +--- -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/adding-wipe-admin.md b/docs/guardian/tokens/retirement-contract/retirement-apis/adding-wipe-admin.md index 9011ee710a..85a7c07e12 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/adding-wipe-admin.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/adding-wipe-admin.md @@ -1,36 +1,40 @@ # Adding Wipe Admin -{% swagger method="post" path="" baseUrl="/contracts/wipe/{contractId}/admin/{hederaId}" summary="Add wipe admin." %} -{% swagger-description %} -Add wipe contract admin. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /api/v1/contracts/wipe/{contractId}/admin/{hederaId}`** -{% swagger-parameter in="path" name="hederaId" type="String" required="true" %} -Hedera Identifier -{% endswagger-parameter %} +Adds a wipe contract admin for the specified Hedera account. Only Standard Registry users are allowed to make this request. -{% swagger-parameter in="path" name="contractId" type="String" required="true" %} -Contract Identifier -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} +**Permission:** `Permissions.CONTRACTS_WIPE_ADMIN_CREATE` -{% endswagger-response %} +--- -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +## Request -{% endswagger-response %} +### Path Parameters -{% swagger-response status="403: Forbidden" description="Forbidden" %} +| Parameter | Type | Required | Description | +|--------------|--------|----------|--------------------------------------------| +| `contractId` | string | Yes | Contract identifier | +| `hederaId` | string | Yes | Hedera account ID to grant admin rights to | -{% endswagger-response %} +--- -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/adding-wipe-for-specific-token.md b/docs/guardian/tokens/retirement-contract/retirement-apis/adding-wipe-for-specific-token.md index 97a4e33293..d86e0ac3c1 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/adding-wipe-for-specific-token.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/adding-wipe-for-specific-token.md @@ -1,5 +1,41 @@ -# Adding Wipe for specific token +# Adding Wipe Wiper for Specific Token -{% openapi src="../../../../.gitbook/assets/swagger (3) (2).yaml" path="/contracts/wipe/{contractId}/wiper/{hederaId}/{tokenId}" method="post" %} -[swagger (3) (2).yaml](<../../../../.gitbook/assets/swagger (3) (2).yaml>) -{% endopenapi %} +**`POST /api/v1/contracts/wipe/{contractId}/wiper/{hederaId}/{tokenId}`** + +Adds a wipe wiper for a specific token within a wipe contract. Only Standard Registry users are allowed to make this request. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.CONTRACTS_WIPER_CREATE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|--------------|--------|----------|------------------------------------------------------| +| `contractId` | string | Yes | Contract identifier | +| `hederaId` | string | Yes | Hedera account ID to grant wiper rights to | +| `tokenId` | string | Yes | Hedera token identifier the wiper rights apply to | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/adding-wipe-manager.md b/docs/guardian/tokens/retirement-contract/retirement-apis/adding-wipe-manager.md index e663d42c04..fd03ce36bb 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/adding-wipe-manager.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/adding-wipe-manager.md @@ -1,36 +1,40 @@ # Adding Wipe Manager -{% swagger method="post" path="" baseUrl="/contracts/wipe/{contractId}/manager/{hederaId}" summary="Add wipe manager." %} -{% swagger-description %} -Add wipe contract manager. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /api/v1/contracts/wipe/{contractId}/manager/{hederaId}`** -{% swagger-parameter in="path" name="hederaId" type="String" required="true" %} -Hedera ID -{% endswagger-parameter %} +Adds a wipe contract manager for the specified Hedera account. Only Standard Registry users are allowed to make this request. -{% swagger-parameter in="path" name="contractId" type="String" required="true" %} -Contract ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} +**Permission:** `Permissions.CONTRACTS_WIPE_MANAGER_CREATE` -{% endswagger-response %} +--- -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +## Request -{% endswagger-response %} +### Path Parameters -{% swagger-response status="403: Forbidden" description="Forbidden" %} +| Parameter | Type | Required | Description | +|--------------|--------|----------|----------------------------------------------| +| `contractId` | string | Yes | Contract identifier | +| `hederaId` | string | Yes | Hedera account ID to grant manager rights to | -{% endswagger-response %} +--- -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/adding-wipe-wiper.md b/docs/guardian/tokens/retirement-contract/retirement-apis/adding-wipe-wiper.md index 50d4d77221..0ea4c7b068 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/adding-wipe-wiper.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/adding-wipe-wiper.md @@ -1,15 +1,40 @@ # Adding Wipe Wiper -{% swagger method="post" path="" baseUrl="/contracts/wipe/{contractId}/wiper/{hederaId}" summary="Add wipe wiper." %} -{% swagger-description %} -Add wipe contract wiper. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} - -{% swagger-parameter in="path" name="hederaId" type="String" required="true" %} -Hedera Identifier -{% endswagger-parameter %} - -{% swagger-parameter in="path" name="contractId" type="String" required="true" %} -Contract Identifier -{% endswagger-parameter %} -{% endswagger %} +**`POST /api/v1/contracts/wipe/{contractId}/wiper/{hederaId}`** + +Adds a wipe contract wiper for the specified Hedera account. Only Standard Registry users are allowed to make this request. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.CONTRACTS_WIPER_CREATE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|--------------|--------|----------|----------------------------------------------| +| `contractId` | string | Yes | Contract identifier | +| `hederaId` | string | Yes | Hedera account ID to grant wiper rights to | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/approving-retire-request.md b/docs/guardian/tokens/retirement-contract/retirement-apis/approving-retire-request.md index dca3ad14d7..aecb34ddcb 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/approving-retire-request.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/approving-retire-request.md @@ -1,32 +1,39 @@ # Approving Retire Request -{% swagger method="post" path="" baseUrl="/contracts/retire/requests/{requestId}/approve" summary="Approve retire request." %} -{% swagger-description %} -Approve retire contract request. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /api/v1/contracts/retire/requests/{requestId}/approve`** -{% swagger-parameter in="path" name="requestId" type="String" required="true" %} -Request Identifier -{% endswagger-parameter %} +Approves a retire contract request. Only Standard Registry users are allowed to make this request. -{% swagger-response status="200: OK" description="Successful Operation" %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% endswagger-response %} +**Permission:** `Permissions.CONTRACTS_RETIRE_REQUEST_REVIEW` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +--- -{% endswagger-response %} +## Request -{% swagger-response status="403: Forbidden" description="Forbidden" %} +### Path Parameters -{% endswagger-response %} +| Parameter | Type | Required | Description | +|-------------|--------|----------|--------------------| +| `requestId` | string | Yes | Request identifier | -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/approving-wipe-requests.md b/docs/guardian/tokens/retirement-contract/retirement-apis/approving-wipe-requests.md index efd2e68b4e..fb776febfa 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/approving-wipe-requests.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/approving-wipe-requests.md @@ -1,32 +1,39 @@ # Approving Wipe Requests -{% swagger method="post" path="" baseUrl="/contracts/wipe/requests/{requestId}/approve" summary="Approve wipe request." %} -{% swagger-description %} -Approve wipe contract request. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /api/v1/contracts/wipe/requests/{requestId}/approve`** -{% swagger-parameter in="path" name="requestId" type="String" required="true" %} -Request Identifier -{% endswagger-parameter %} +Approves a wipe contract request. Only Standard Registry users are allowed to make this request. -{% swagger-response status="200: OK" description="Successful Operation" %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% endswagger-response %} +**Permission:** `Permissions.CONTRACTS_WIPE_REQUEST_REVIEW` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +--- -{% endswagger-response %} +## Request -{% swagger-response status="403: Forbidden" description="Forbidden" %} +### Path Parameters -{% endswagger-response %} +| Parameter | Type | Required | Description | +|-------------|--------|----------|--------------------| +| `requestId` | string | Yes | Request identifier | -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -ontent: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/cancelling-retire-request.md b/docs/guardian/tokens/retirement-contract/retirement-apis/cancelling-retire-request.md index 2e193f577b..4e439f4937 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/cancelling-retire-request.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/cancelling-retire-request.md @@ -1,32 +1,39 @@ # Cancelling Retire Request -{% swagger method="delete" path="" baseUrl="/contracts/retire/requests/{requestId}/cancel" summary="Cancel retire request." %} -{% swagger-description %} -Cancel retire contract request. -{% endswagger-description %} +**`DELETE /api/v1/contracts/retire/requests/{requestId}/cancel`** -{% swagger-parameter in="path" name="requestId" type="String" required="true" %} -Request Identifier -{% endswagger-parameter %} +Cancels a retire contract request. Accessible by Standard Registry and User roles. -{% swagger-response status="200: OK" description="Successful Operation" %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% endswagger-response %} +**Permission:** `Permissions.CONTRACTS_RETIRE_REQUEST_CREATE` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +--- -{% endswagger-response %} +## Request -{% swagger-response status="403: Forbidden" description="Forbidden" %} +### Path Parameters -{% endswagger-response %} +| Parameter | Type | Required | Description | +|-------------|--------|----------|--------------------| +| `requestId` | string | Yes | Request identifier | -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/clearing-wipe-requests.md b/docs/guardian/tokens/retirement-contract/retirement-apis/clearing-wipe-requests.md index 157811ba71..073146ddfb 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/clearing-wipe-requests.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/clearing-wipe-requests.md @@ -1,32 +1,39 @@ # Clearing Wipe Requests -{% swagger method="delete" path="" baseUrl="/contracts/wipe/{contractId}/requests" summary="Clear wipe requests." %} -{% swagger-description %} -Clear wipe contract requests. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`DELETE /api/v1/contracts/wipe/{contractId}/requests`** -{% swagger-parameter in="path" name="contractId" type="String" required="true" %} -Contract Identifier -{% endswagger-parameter %} +Clears all wipe requests for the specified contract. Only Standard Registry users are allowed to make this request. -{% swagger-response status="200: OK" description="Successful Operation" %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% endswagger-response %} +**Permission:** `Permissions.CONTRACTS_WIPE_REQUEST_DELETE` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +--- -{% endswagger-response %} +## Request -{% swagger-response status="403: Forbidden" description="Forbidden" %} +### Path Parameters -{% endswagger-response %} +| Parameter | Type | Required | Description | +|--------------|--------|----------|---------------------| +| `contractId` | string | Yes | Contract identifier | -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/creating-new-contract.md b/docs/guardian/tokens/retirement-contract/retirement-apis/creating-new-contract.md index a56e97dae3..07dac51e96 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/creating-new-contract.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/creating-new-contract.md @@ -1,49 +1,53 @@ -# Creating new Contract +# Creating a New Contract -{% swagger method="post" path="" baseUrl="/contracts" summary="Creates new contract" %} -{% swagger-description %} -Creates new contract. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /api/v1/contracts`** -{% swagger-parameter in="body" type="String" required="true" %} -Request Object Parameters. -{% endswagger-parameter %} +Creates a new smart contract. Only Standard Registry users are allowed to make this request. -{% swagger-response status="201: Created" description="Created Contract" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/ContractDTO' -} -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +**Permission:** `Permissions.CONTRACTS_CONTRACT_CREATE` + +--- + +## Request -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +### Request Body + +```json { - // Response + "description": "Example retire contract", + "type": "RETIRE" } ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +| Field | Type | Required | Description | +|---------------|--------|----------|---------------------------------------------------| +| `description` | string | No | Human-readable description of the contract | +| `type` | string | Yes | Contract type: `RETIRE` or `WIPE` | + +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' + "id": "63e3e5e8a01b3c001234abcd", + "contractId": "0.0.4532001", + "description": "Example retire contract", + "type": "RETIRE", + "owner": "example_user" } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/deleting-retire-pools.md b/docs/guardian/tokens/retirement-contract/retirement-apis/deleting-retire-pools.md index 8fb9240ea2..87d2a28223 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/deleting-retire-pools.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/deleting-retire-pools.md @@ -1,37 +1,39 @@ # Deleting Retire Pools -{% swagger method="delete" path="" baseUrl=" /contracts/retire/{contractId}/pools" summary="Clear retire pools." %} -{% swagger-description %} -Clear retire contract pools. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`DELETE /api/v1/contracts/retire/{contractId}/pools`** -{% swagger-parameter in="path" name="contractId" type="String" %} -Contract Identifier -{% endswagger-parameter %} +Clears all retire pools for the specified contract. Only Standard Registry users are allowed to make this request. -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - type: boolean -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +**Permission:** `Permissions.CONTRACTS_POOL_DELETE` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} +## Request -{% endswagger-response %} +### Path Parameters -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +| Parameter | Type | Required | Description | +|--------------|--------|----------|---------------------| +| `contractId` | string | Yes | Contract identifier | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/deleting-retire-requests.md b/docs/guardian/tokens/retirement-contract/retirement-apis/deleting-retire-requests.md index 26413007a2..5b915bce62 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/deleting-retire-requests.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/deleting-retire-requests.md @@ -1,37 +1,39 @@ # Deleting Retire Requests -{% swagger method="delete" path="" baseUrl="/contracts/retire/{contractId}/requests" summary="Clear retire requests." %} -{% swagger-description %} -Clear retire contract requests. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`DELETE /api/v1/contracts/retire/{contractId}/requests`** -{% swagger-parameter in="path" name="contractId" type="String" %} -Contract Identifier -{% endswagger-parameter %} +Clears all retire requests for the specified contract. Only Standard Registry users are allowed to make this request. -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - type: boolean -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +**Permission:** `Permissions.CONTRACTS_RETIRE_REQUEST_DELETE` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} +## Request -{% endswagger-response %} +### Path Parameters -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +| Parameter | Type | Required | Description | +|--------------|--------|----------|---------------------| +| `contractId` | string | Yes | Contract identifier | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/deleting-wipe-request-for-hedera-account.md b/docs/guardian/tokens/retirement-contract/retirement-apis/deleting-wipe-request-for-hedera-account.md index bf085c8ca0..888c554ddf 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/deleting-wipe-request-for-hedera-account.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/deleting-wipe-request-for-hedera-account.md @@ -1,5 +1,40 @@ -# Deleting Wipe request for Hedera Account +# Deleting Wipe Requests for Hedera Account -{% openapi src="../../../../.gitbook/assets/swagger (3) (2).yaml" path="/contracts/wipe/{contractId}/requests/{hederaId}" method="delete" %} -[swagger (3) (2).yaml](<../../../../.gitbook/assets/swagger (3) (2).yaml>) -{% endopenapi %} +**`DELETE /api/v1/contracts/wipe/{contractId}/requests/{hederaId}`** + +Clears all wipe requests for a specific Hedera account within a contract. Only Standard Registry users are allowed to make this request. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.CONTRACTS_WIPE_REQUEST_DELETE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|--------------|--------|----------|--------------------------------------------------------| +| `contractId` | string | Yes | Contract identifier | +| `hederaId` | string | Yes | Hedera account ID whose wipe requests will be cleared | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/disabling-wipe-requests.md b/docs/guardian/tokens/retirement-contract/retirement-apis/disabling-wipe-requests.md index 8987c21daa..2f5fdfe1a4 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/disabling-wipe-requests.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/disabling-wipe-requests.md @@ -1,32 +1,39 @@ # Disabling Wipe Requests -{% swagger method="post" path="" baseUrl="/contracts/wipe/{contractId}/requests/disable" summary="Disable wipe requests." %} -{% swagger-description %} -Disable wipe contract requests. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /api/v1/contracts/wipe/{contractId}/requests/disable`** -{% swagger-parameter in="path" name="contractId" type="String" required="false" %} -Contract Identifier -{% endswagger-parameter %} +Disables wipe requests for the specified contract. Only Standard Registry users are allowed to make this request. -{% swagger-response status="200: OK" description="Successful Operation" %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% endswagger-response %} +**Permission:** `Permissions.CONTRACTS_WIPE_REQUEST_UPDATE` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +--- -{% endswagger-response %} +## Request -{% swagger-response status="403: Forbidden" description="Forbidden" %} +### Path Parameters -{% endswagger-response %} +| Parameter | Type | Required | Description | +|--------------|--------|----------|---------------------| +| `contractId` | string | Yes | Contract identifier | -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/enabling-wipe-requests.md b/docs/guardian/tokens/retirement-contract/retirement-apis/enabling-wipe-requests.md index 2708c3e54d..e1f249bf8b 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/enabling-wipe-requests.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/enabling-wipe-requests.md @@ -1,32 +1,39 @@ # Enabling Wipe Requests -{% swagger method="post" path="" baseUrl="/contracts/wipe/{contractId}/requests/enable" summary="Enable wipe requests." %} -{% swagger-description %} -Enable wipe contract requests. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /api/v1/contracts/wipe/{contractId}/requests/enable`** -{% swagger-parameter in="path" name="contractId" type="String" %} -Contract Identifier -{% endswagger-parameter %} +Enables wipe requests for the specified contract. Only Standard Registry users are allowed to make this request. -{% swagger-response status="200: OK" description="Successful Operation" %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% endswagger-response %} +**Permission:** `Permissions.CONTRACTS_WIPE_REQUEST_UPDATE` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +--- -{% endswagger-response %} +## Request -{% swagger-response status="403: Forbidden" description="Forbidden" %} +### Path Parameters -{% endswagger-response %} +| Parameter | Type | Required | Description | +|--------------|--------|----------|---------------------| +| `contractId` | string | Yes | Contract identifier | -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/get-contract-permissions.md b/docs/guardian/tokens/retirement-contract/retirement-apis/get-contract-permissions.md index 49065114ae..a2bac1e0b0 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/get-contract-permissions.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/get-contract-permissions.md @@ -1,41 +1,41 @@ # Get Contract Permissions -## Get contract permissions. +**`GET /api/v1/contracts/{contractId}/permissions`** -`GET` `/contracts/{contractId}/permissions` +Returns the permission flags for the specified smart contract. Only Standard Registry users are allowed to make this request. -Get smart-contract permissions. Only users with the Standard Registry role are allowed to make the request. +**Authentication:** Bearer token required (`Authorization: Bearer `) -#### Path Parameters +**Permission:** `Permissions.CONTRACTS_PERMISSIONS_READ` -| Name | Type | Description | -| -------------------------------------------- | ------ | ------------------- | -| contractID\* | String | Contract Identifier | +--- -{% tabs %} -{% tab title="200: OK Contract Permissions" %} -``` -content: - application/json: - schema: - type: number -``` -{% endtab %} +## Request -{% tab title="401: Unauthorized Unauthorized" %} +### Path Parameters -{% endtab %} +| Parameter | Type | Required | Description | +|--------------|--------|----------|---------------------| +| `contractId` | string | Yes | Contract identifier | -{% tab title="403: Forbidden Forbidden" %} +--- -{% endtab %} +## Response -{% tab title="500: Internal Server Error Internal Server Error" %} -``` - content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +### Success Response + +**Status:** `200 OK` + +```json +3 ``` -{% endtab %} -{% endtabs %} + +The response is a numeric bitmask representing the caller's permissions on the contract. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/importing-new-contract.md b/docs/guardian/tokens/retirement-contract/retirement-apis/importing-new-contract.md index da5eaec540..9ffb878d46 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/importing-new-contract.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/importing-new-contract.md @@ -1,49 +1,53 @@ -# Importing new Contract +# Importing a New Contract -{% swagger method="post" path="" baseUrl="/contracts/import" summary="Import new contract" %} -{% swagger-description %} -Creates new contract. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /api/v1/contracts/import`** -{% swagger-parameter in="body" name="contractId" type="String" required="true" %} -Request Object Parameters. -{% endswagger-parameter %} +Imports an existing smart contract by its Hedera contract ID. Only Standard Registry users are allowed to make this request. -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/ContractDTO' -} -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +**Permission:** `Permissions.CONTRACTS_CONTRACT_CREATE` + +--- + +## Request -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +### Request Body + +```json { - // Response + "contractId": "0.0.4532001", + "description": "Imported retire contract" } ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +| Field | Type | Required | Description | +|---------------|--------|----------|--------------------------------------------------------| +| `contractId` | string | Yes | The Hedera identifier of the contract to import | +| `description` | string | No | Human-readable description of the imported contract | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' + "id": "63e3e5e8a01b3c001234abcd", + "contractId": "0.0.4532001", + "description": "Imported retire contract", + "type": "RETIRE", + "owner": "example_user" } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/rejecting-wipe-requests.md b/docs/guardian/tokens/retirement-contract/retirement-apis/rejecting-wipe-requests.md index 21318660ac..b2e11de40b 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/rejecting-wipe-requests.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/rejecting-wipe-requests.md @@ -1,36 +1,45 @@ # Rejecting Wipe Requests -{% swagger method="delete" path="" baseUrl="/contracts/wipe/requests/{requestId}/reject" summary="Reject wipe request." %} -{% swagger-description %} -Reject wipe contract request. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`DELETE /api/v1/contracts/wipe/requests/{requestId}/reject`** -{% swagger-parameter in="query" name="ban" type="boolean" %} -Reject and ban -{% endswagger-parameter %} +Rejects a wipe contract request, optionally banning the requester. Only Standard Registry users are allowed to make this request. -{% swagger-parameter in="path" name="requestId" type="String" required="true" %} -Request Identifier -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} +**Permission:** `Permissions.CONTRACTS_WIPE_REQUEST_REVIEW` -{% endswagger-response %} +--- -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +## Request -{% endswagger-response %} +### Path Parameters -{% swagger-response status="403: Forbidden" description="Forbidden" %} +| Parameter | Type | Required | Description | +|-------------|--------|----------|--------------------| +| `requestId` | string | Yes | Request identifier | -{% endswagger-response %} +### Query Parameters -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +| Parameter | Type | Required | Default | Description | +|-----------|---------|----------|---------|----------------------------------------------| +| `ban` | boolean | No | false | If `true`, also bans the requester's account | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/removing-contract.md b/docs/guardian/tokens/retirement-contract/retirement-apis/removing-contract.md index fec8d847bb..4d2bf91ae9 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/removing-contract.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/removing-contract.md @@ -1,37 +1,39 @@ -# Removing Contract +# Removing a Contract -{% swagger method="delete" path="" baseUrl="/contracts/{contractId}" summary="Remove contract." %} -{% swagger-description %} -Remove smart-contract. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`DELETE /api/v1/contracts/{contractId}`** -{% swagger-parameter in="path" name="contractId" type="String" required="true" %} -Contract Identifier -{% endswagger-parameter %} +Removes a smart contract. Only Standard Registry users are allowed to make this request. -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - type: boolean -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +**Permission:** `Permissions.CONTRACTS_CONTRACT_DELETE` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} +## Request -{% endswagger-response %} +### Path Parameters -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +| Parameter | Type | Required | Description | +|--------------|--------|----------|---------------------| +| `contractId` | string | Yes | Contract identifier | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/removing-retire-admin.md b/docs/guardian/tokens/retirement-contract/retirement-apis/removing-retire-admin.md index 8fd4bd51a3..afa90cd93d 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/removing-retire-admin.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/removing-retire-admin.md @@ -1,36 +1,40 @@ # Removing Retire Admin -{% swagger method="delete" path="" baseUrl="/contracts/retire/{contractId}/admin/{hederaId}" summary="Remove retire admin." %} -{% swagger-description %} -Remove retire contract admin. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`DELETE /api/v1/contracts/retire/{contractId}/admin/{hederaId}`** -{% swagger-parameter in="path" name="hederaId" type="String" required="true" %} -Hedera Identifier -{% endswagger-parameter %} +Removes a retire contract admin for the specified Hedera account. Only Standard Registry users are allowed to make this request. -{% swagger-parameter in="path" name="contractId" type="String" required="true" %} -Contract Identifier -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} +**Permission:** `Permissions.CONTRACTS_RETIRE_ADMIN_DELETE` -{% endswagger-response %} +--- -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +## Request -{% endswagger-response %} +### Path Parameters -{% swagger-response status="403: Forbidden" description="Forbidden" %} +| Parameter | Type | Required | Description | +|--------------|--------|----------|---------------------------------------------| +| `contractId` | string | Yes | Contract identifier | +| `hederaId` | string | Yes | Hedera account ID to revoke admin rights from | -{% endswagger-response %} +--- -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/removing-wipe-admin.md b/docs/guardian/tokens/retirement-contract/retirement-apis/removing-wipe-admin.md index eb2c7cb1d7..4bcfae9055 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/removing-wipe-admin.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/removing-wipe-admin.md @@ -1,36 +1,40 @@ # Removing Wipe Admin -{% swagger method="delete" path="" baseUrl="/contracts/wipe/{contractId}/admin/{hederaId}" summary="Remove wipe admin." %} -{% swagger-description %} -Remove wipe contract admin. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`DELETE /api/v1/contracts/wipe/{contractId}/admin/{hederaId}`** -{% swagger-parameter in="path" name="hederaId" type="String" required="true" %} -Hedera Identifier -{% endswagger-parameter %} +Removes a wipe contract admin for the specified Hedera account. Only Standard Registry users are allowed to make this request. -{% swagger-parameter in="path" name="contractId" type="String" required="true" %} -Contract Identifier -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} +**Permission:** `Permissions.CONTRACTS_WIPE_ADMIN_DELETE` -{% endswagger-response %} +--- -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +## Request -{% endswagger-response %} +### Path Parameters -{% swagger-response status="403: Forbidden" description="Forbidden" %} +| Parameter | Type | Required | Description | +|--------------|--------|----------|----------------------------------------------| +| `contractId` | string | Yes | Contract identifier | +| `hederaId` | string | Yes | Hedera account ID to revoke admin rights from | -{% endswagger-response %} +--- -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/removing-wipe-manager.md b/docs/guardian/tokens/retirement-contract/retirement-apis/removing-wipe-manager.md index 9806d89b4b..c0cb278a5c 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/removing-wipe-manager.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/removing-wipe-manager.md @@ -1,36 +1,40 @@ # Removing Wipe Manager -{% swagger method="delete" path="" baseUrl="/contracts/wipe/{contractId}/manager/{hederaId}" summary="Remove wipe manager" %} -{% swagger-description %} -Remove wipe contract manager. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`DELETE /api/v1/contracts/wipe/{contractId}/manager/{hederaId}`** -{% swagger-parameter in="path" name="hederaId" type="String" required="true" %} -Hedera Identifier -{% endswagger-parameter %} +Removes a wipe contract manager for the specified Hedera account. Only Standard Registry users are allowed to make this request. -{% swagger-parameter in="path" name="contractId" type="String" required="true" %} -Contract Identifier -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} +**Permission:** `Permissions.CONTRACTS_WIPE_MANAGER_DELETE` -{% endswagger-response %} +--- -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +## Request -{% endswagger-response %} +### Path Parameters -{% swagger-response status="403: Forbidden" description="Forbidden" %} +| Parameter | Type | Required | Description | +|--------------|--------|----------|------------------------------------------------| +| `contractId` | string | Yes | Contract identifier | +| `hederaId` | string | Yes | Hedera account ID to revoke manager rights from | -{% endswagger-response %} +--- -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/removing-wipe-wiper.md b/docs/guardian/tokens/retirement-contract/retirement-apis/removing-wipe-wiper.md index 9e9e37ec0b..588b7c52ba 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/removing-wipe-wiper.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/removing-wipe-wiper.md @@ -1,36 +1,40 @@ # Removing Wipe Wiper -{% swagger method="delete" path="" baseUrl="/contracts/wipe/{contractId}/wiper/{hederaId}" summary="Remove wipe wiper" %} -{% swagger-description %} -Remove wipe contract wiper. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`DELETE /api/v1/contracts/wipe/{contractId}/wiper/{hederaId}`** -{% swagger-parameter in="path" name="hederaId" type="String" required="true" %} -Hedera Identifier -{% endswagger-parameter %} +Removes a wipe contract wiper for the specified Hedera account. Only Standard Registry users are allowed to make this request. -{% swagger-parameter in="path" name="contractId" type="String" required="true" %} -Contract Identifier -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} +**Permission:** `Permissions.CONTRACTS_WIPER_DELETE` -{% endswagger-response %} +--- -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +## Request -{% endswagger-response %} +### Path Parameters -{% swagger-response status="403: Forbidden" description="Forbidden" %} +| Parameter | Type | Required | Description | +|--------------|--------|----------|-----------------------------------------------| +| `contractId` | string | Yes | Contract identifier | +| `hederaId` | string | Yes | Hedera account ID to revoke wiper rights from | -{% endswagger-response %} +--- -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/retiring-tokens.md b/docs/guardian/tokens/retirement-contract/retirement-apis/retiring-tokens.md index dce96f6468..08c71788f7 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/retiring-tokens.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/retiring-tokens.md @@ -1,37 +1,60 @@ # Retiring Tokens -{% swagger method="post" path="" baseUrl="/contracts/retire/pools/{poolId}/retire" summary="Retire tokens." %} -{% swagger-description %} -Retire tokens. -{% endswagger-description %} +**`POST /api/v1/contracts/retire/pools/{poolId}/retire`** -{% swagger-parameter in="path" name="poolId" type="String" %} -Pool Identifier -{% endswagger-parameter %} +Submits a token retirement request against the specified pool. Accessible by Standard Registry and User roles. -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - type: boolean -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.CONTRACTS_RETIRE_REQUEST_CREATE` + +--- -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +## Request -{% endswagger-response %} +### Path Parameters -{% swagger-response status="403: Forbidden" description="Forbidden" %} +| Parameter | Type | Required | Description | +|-----------|--------|----------|-----------------| +| `poolId` | string | Yes | Pool identifier | -{% endswagger-response %} +### Request Body -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} +```json +[ + { + "token": "0.0.5000001", + "count": 100, + "serials": [] + } +] ``` - content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' + +The request body is an array of token retirement entries. + +| Field | Type | Required | Description | +|-----------|--------|----------|-----------------------------------------------------| +| `token` | string | Yes | Hedera token identifier to retire | +| `count` | number | Yes | Number of tokens to retire | +| `serials` | array | No | Specific serial numbers (for non-fungible tokens) | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `400 Bad Request` | Request body must be an array | +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/returning-all-retired-vcs.md b/docs/guardian/tokens/retirement-contract/retirement-apis/returning-all-retired-vcs.md index dbee63bab8..d587dcbd90 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/returning-all-retired-vcs.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/returning-all-retired-vcs.md @@ -1,48 +1,53 @@ -# Returning all Retired VCs +# Returning All Retired VCs -{% swagger method="get" path="" baseUrl="/contracts/retire" summary="Return a list of all retire vcs." %} -{% swagger-description %} -Returns all retire vcs. -{% endswagger-description %} +**`GET /api/v1/contracts/retire`** -{% swagger-parameter in="query" name="pageSize" type="number" required="false" %} -The numbers of items to return -{% endswagger-parameter %} +Returns a paginated list of all retire VC documents. Accessible by Standard Registry and User roles. -{% swagger-parameter in="query" name="pageIndex" type="number" %} -The number of pages to skip before starting to collect the result set -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -headers: - x-total-count: - schema: - type: integer - description: Total items in the collection. - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/' -``` -{% endswagger-response %} +**Permission:** `Permissions.CONTRACTS_DOCUMENT_READ` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +--- -{% endswagger-response %} +## Request -{% swagger-response status="403: Forbidden" description="Forbidden" %} +### Query Parameters -{% endswagger-response %} +| Parameter | Type | Required | Default | Description | +|-------------|--------|----------|---------|-------------------------------------------------------------------| +| `pageIndex` | number | No | 0 | The number of pages to skip before starting to collect the result | +| `pageSize` | number | No | 20 | The number of items to return | -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +Headers: + +| Header | Description | +|-----------------|--------------------------------------| +| `X-Total-Count` | Total number of retire VCs available | + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "hash": "abc123", + "document": {} + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/returning-list-of-all-retire-pools.md b/docs/guardian/tokens/retirement-contract/retirement-apis/returning-list-of-all-retire-pools.md index eda1f9fdcc..86fdd896e8 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/returning-list-of-all-retire-pools.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/returning-list-of-all-retire-pools.md @@ -1,56 +1,60 @@ -# Returning list of all Retire Pools +# Returning List of All Retire Pools -{% swagger method="get" path="" baseUrl="/contracts/retire/pools" summary="Return a list of all retire pools." %} -{% swagger-description %} -Returns all retire pools. -{% endswagger-description %} +**`GET /api/v1/contracts/retire/pools`** -{% swagger-parameter in="query" name="tokens" type="String" %} -Tokens -{% endswagger-parameter %} +Returns a paginated list of all retire pools. Accessible by Standard Registry and User roles. -{% swagger-parameter in="query" name="contractId" type="String" %} -Contract Identifier -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-parameter in="query" name="pageSize" type="number" %} -The numbers of items to return -{% endswagger-parameter %} +**Permission:** `Permissions.CONTRACTS_POOL_READ` -{% swagger-parameter in="query" name="pageIndex" type="number" %} -The number of pages to skip before starting to collect the result set -{% endswagger-parameter %} +--- -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -headers: - x-total-count: - schema: - type: integer - description: Total items in the collection. - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/RetirePoolDTO' -``` -{% endswagger-response %} +## Request -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +### Query Parameters -{% endswagger-response %} +| Parameter | Type | Required | Default | Description | +|--------------|--------|----------|---------|-------------------------------------------------------------------| +| `contractId` | string | No | — | Filter pools by contract identifier | +| `tokens` | string | No | — | Comma-separated list of token identifiers to filter by | +| `pageIndex` | number | No | 0 | The number of pages to skip before starting to collect the result | +| `pageSize` | number | No | 20 | The number of items to return | -{% swagger-response status="403: Forbidden" description="Forbidden" %} +--- -{% endswagger-response %} +## Response -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +### Success Response + +**Status:** `200 OK` + +Headers: + +| Header | Description | +|-----------------|--------------------------------------| +| `X-Total-Count` | Total number of retire pools available | + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "contractId": "0.0.4532001", + "tokens": [ + { + "token": "0.0.5000001", + "count": 100 + } + ], + "enabled": true + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/returning-list-of-all-retire-requests.md b/docs/guardian/tokens/retirement-contract/retirement-apis/returning-list-of-all-retire-requests.md index 146338e8c6..4b39695ea2 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/returning-list-of-all-retire-requests.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/returning-list-of-all-retire-requests.md @@ -1,47 +1,59 @@ -# Returning list of all Retire Requests +# Returning List of All Retire Requests -{% swagger method="get" path="" baseUrl="/contracts/retire/requests" summary="Return a list of all retire requests." %} -{% swagger-description %} -Returns all retire requests. -{% endswagger-description %} +**`GET /api/v1/contracts/retire/requests`** -{% swagger-parameter in="query" name="contractId" type="String" %} -Contract Identifier -{% endswagger-parameter %} +Returns a paginated list of all retire requests. Accessible by Standard Registry and User roles. -{% swagger-parameter in="query" name="pageSize" type="Number" required="false" %} -The numbers of items to return -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-parameter in="query" name="pageIndex" type="Number" %} -The number of pages to skip before starting to collect the result set -{% endswagger-parameter %} +**Permission:** `Permissions.CONTRACTS_RETIRE_REQUEST_READ` -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -headers: - x-total-count: - schema: - type: integer - description: Total items in the collection. - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/RetireRequestDTO' -``` -{% endswagger-response %} +--- + +## Request + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|--------------|--------|----------|---------|-------------------------------------------------------------------| +| `contractId` | string | No | — | Filter requests by contract identifier | +| `pageIndex` | number | No | 0 | The number of pages to skip before starting to collect the result | +| `pageSize` | number | No | 20 | The number of items to return | -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +--- -{% endswagger-response %} +## Response -{% swagger-response status="403: Forbidden" description="Forbidden" %} +### Success Response -{% endswagger-response %} +**Status:** `200 OK` + +Headers: + +| Header | Description | +|-----------------|------------------------------------------| +| `X-Total-Count` | Total number of retire requests available | + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "contractId": "0.0.4532001", + "user": "0.0.4532001", + "tokens": [ + { + "token": "0.0.5000001", + "count": 100 + } + ] + } +] +``` -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} +### Error Responses -{% endswagger-response %} -{% endswagger %} +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/returns-a-list-of-all-wipe-requests.md b/docs/guardian/tokens/retirement-contract/retirement-apis/returns-a-list-of-all-wipe-requests.md index 909e3ca23c..81fbc3b95d 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/returns-a-list-of-all-wipe-requests.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/returns-a-list-of-all-wipe-requests.md @@ -1,53 +1,59 @@ -# Returns a list of all Wipe requests +# Returns a List of All Wipe Requests -{% swagger method="get" path="" baseUrl="/contracts/wipe/requests" summary="Return a list of all wipe requests" %} -{% swagger-description %} -Returns all wipe requests. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`GET /api/v1/contracts/wipe/requests`** -{% swagger-parameter in="query" name="contractId" type="String" %} -Contract Identifier -{% endswagger-parameter %} +Returns a paginated list of all wipe requests. Only Standard Registry users are allowed to make this request. -{% swagger-parameter in="query" name="pageSize" type="number" %} -The numbers of items to return -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-parameter in="query" name="pageIndex" type="number" %} -The number of pages to skip before starting to collect the result -{% endswagger-parameter %} +**Permission:** `Permissions.CONTRACTS_WIPE_REQUEST_READ` -{% swagger-response status="200: OK" description="Successful Operation" %} -``` - headers: - x-total-count: - schema: - type: integer - description: Total items in the collection. - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/WiperRequestDTO' +--- -``` -{% endswagger-response %} +## Request -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +### Query Parameters -{% endswagger-response %} +| Parameter | Type | Required | Default | Description | +|--------------|--------|----------|---------|-------------------------------------------------------------------| +| `contractId` | string | No | — | Filter requests by contract identifier | +| `pageIndex` | number | No | 0 | The number of pages to skip before starting to collect the result | +| `pageSize` | number | No | 20 | The number of items to return | -{% swagger-response status="403: Forbidden" description="Forbidden" %} +--- -{% endswagger-response %} +## Response -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +### Success Response + +**Status:** `200 OK` + +Headers: + +| Header | Description | +|-----------------|----------------------------------------| +| `X-Total-Count` | Total number of wipe requests available | + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "contractId": "0.0.4532001", + "user": "0.0.4532001", + "tokens": [ + { + "token": "0.0.5000001", + "count": 50 + } + ] + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/returns-all-contracts.md b/docs/guardian/tokens/retirement-contract/retirement-apis/returns-all-contracts.md index 21134876f0..474cc9042d 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/returns-all-contracts.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/returns-all-contracts.md @@ -1,62 +1,55 @@ -# Returning all contracts - -## Returns all contracts. - -`GET` `/contracts` - -Returns all contracts. - -#### Query Parameters - -| Name | Type | Description | -| ------------------------------------------- | ------- | --------------------------------------------------------------------- | -| pageIndex\* | Integer | The number of pages to skip before starting to collect the result set | -| pageSize\* | Integer | The numbers of items to return | -| type | String | Contract type | - -{% tabs %} -{% tab title="200: OK Successful Operation" %} -```javascript -{ - headers: - x-total-count: - schema: - type: integer - description: Total items in the collection. - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/Contract' -} -``` -{% endtab %} +# Returns All Contracts -{% tab title="401: Unauthorized Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endtab %} +**`GET /api/v1/contracts`** -{% tab title="403: Forbidden Forbidden" %} -```javascript -{ - // Response -} -``` -{% endtab %} - -{% tab title="500: Internal Server Error Internal Server Error" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} +Returns a paginated list of all smart contracts. Accessible by Standard Registry and User roles. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.CONTRACTS_CONTRACT_READ` + +--- + +## Request + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-------------|---------|----------|---------|-------------------------------------------------------------------| +| `pageIndex` | number | No | 0 | The number of pages to skip before starting to collect the result | +| `pageSize` | number | No | 20 | The number of items to return | +| `type` | string | No | — | Filter by contract type (`RETIRE` or `WIPE`) | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +Headers: + +| Header | Description | +|-----------------|------------------------------------| +| `X-Total-Count` | Total number of contracts available | + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "contractId": "0.0.4532001", + "description": "Example retire contract", + "type": "RETIRE", + "owner": "example_user" + } +] ``` -{% endtab %} -{% endtabs %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/setting-retire-pools.md b/docs/guardian/tokens/retirement-contract/retirement-apis/setting-retire-pools.md index 4995a131db..11838a0058 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/setting-retire-pools.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/setting-retire-pools.md @@ -1,37 +1,72 @@ # Setting Retire Pools -{% swagger method="post" path="" baseUrl=" /contracts/retire/{contractId}/pools" summary="Set retire pool." %} -{% swagger-description %} -Set retire contract pool. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /api/v1/contracts/retire/{contractId}/pools`** -{% swagger-parameter in="path" name="contractId" type="String" %} -Contract Identifier -{% endswagger-parameter %} +Sets a retire pool for the specified contract. Only Standard Registry users are allowed to make this request. -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/RetirePoolDTO' -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.CONTRACTS_POOL_UPDATE` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +--- -{% endswagger-response %} +## Request -{% swagger-response status="403: Forbidden" description="Forbidden" %} +### Path Parameters -{% endswagger-response %} +| Parameter | Type | Required | Description | +|--------------|--------|----------|---------------------| +| `contractId` | string | Yes | Contract identifier | -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} +### Request Body + +```json +{ + "tokens": [ + { + "token": "0.0.5000001", + "count": 100, + "serials": [] + } + ], + "immediately": false +} ``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' + +| Field | Type | Required | Description | +|----------------|---------|----------|-------------------------------------------------------| +| `tokens` | array | Yes | List of token configurations for the pool | +| `tokens[].token` | string | Yes | Hedera token identifier | +| `tokens[].count` | number | Yes | Number of tokens required for retirement | +| `tokens[].serials` | array | No | Specific serial numbers (for non-fungible tokens) | +| `immediately` | boolean | No | Whether to immediately enable the pool | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "contractId": "0.0.4532001", + "tokens": [ + { + "token": "0.0.5000001", + "count": 100 + } + ], + "enabled": true +} ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/syncing-retire-pools.md b/docs/guardian/tokens/retirement-contract/retirement-apis/syncing-retire-pools.md index 019c24391b..a383f9e96f 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/syncing-retire-pools.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/syncing-retire-pools.md @@ -1,37 +1,41 @@ # Syncing Retire Pools -{% swagger method="post" path="" baseUrl="/contracts/retire/{contractId}/pools/sync" summary="Sync retire pools." %} -{% swagger-description %} -Sync retire contract pools. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /api/v1/contracts/retire/{contractId}/pools/sync`** -{% swagger-parameter in="path" name="contractId" type="String" required="false" %} -Contract Identifier -{% endswagger-parameter %} +Synchronises the retire pools for the specified contract with on-chain data. Only Standard Registry users are allowed to make this request. -{% swagger-response status="200: OK" description="Sync Date" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/Date' -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +**Permission:** `Permissions.CONTRACTS_POOL_UPDATE` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} +## Request -{% endswagger-response %} +### Path Parameters -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +| Parameter | Type | Required | Description | +|--------------|--------|----------|---------------------| +| `contractId` | string | Yes | Contract identifier | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +"2024-01-15T10:30:00.000Z" ``` -{% endswagger-response %} -{% endswagger %} + +The response is an ISO 8601 date string representing the time the sync was completed. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/retirement-contract/retirement-apis/unsetting-retire-pool.md b/docs/guardian/tokens/retirement-contract/retirement-apis/unsetting-retire-pool.md index 7760934db9..2f44d61fc5 100644 --- a/docs/guardian/tokens/retirement-contract/retirement-apis/unsetting-retire-pool.md +++ b/docs/guardian/tokens/retirement-contract/retirement-apis/unsetting-retire-pool.md @@ -1,37 +1,39 @@ # Unsetting Retire Pool -{% swagger method="delete" path="" baseUrl="/contracts/retire/pools/{poolId}" summary="Unset retire pool." %} -{% swagger-description %} -Unset retire contract pool. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`DELETE /api/v1/contracts/retire/pools/{poolId}`** -{% swagger-parameter in="path" name="poolId" type="String" %} -Pool Identifier -{% endswagger-parameter %} +Removes a specific retire pool by its ID. Only Standard Registry users are allowed to make this request. -{% swagger-response status="200: OK" description="Successful Operation" %} -``` -content: - application/json: - schema: - type: boolean -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +**Permission:** `Permissions.CONTRACTS_POOL_DELETE` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} +## Request -{% endswagger-response %} +### Path Parameters -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +| Parameter | Type | Required | Description | +|-----------|--------|----------|------------------| +| `poolId` | string | Yes | Pool identifier | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/token-operations/token-apis/README.md b/docs/guardian/tokens/token-operations/token-apis/README.md index 8bab83ae87..990e113aa6 100644 --- a/docs/guardian/tokens/token-operations/token-apis/README.md +++ b/docs/guardian/tokens/token-operations/token-apis/README.md @@ -1,2 +1,32 @@ # Token APIs +Endpoints for listing Hedera tokens and managing user token associations, KYC status, and freeze status in Guardian. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `GET` | `/api/v1/tokens` | Returns all tokens; includes balances and statuses for non-Standard-Registry users | Yes | +| `POST` | `/api/v1/tokens/{tokenId}/{username}/associate` | Associates a user with the specified token | Yes | +| `DELETE` | `/api/v1/tokens/{tokenId}/{username}/dissociate` | Disassociates a user from the specified token | Yes | +| `PUT` | `/api/v1/tokens/{tokenId}/{username}/freeze` | Freezes the user's token balance | Yes | +| `PUT` | `/api/v1/tokens/{tokenId}/{username}/unfreeze` | Unfreezes the user's token balance | Yes | +| `PUT` | `/api/v1/tokens/{tokenId}/{username}/grantKyc` | Grants KYC status to the user for the token | Yes | +| `PUT` | `/api/v1/tokens/{tokenId}/{username}/revokeKyc` | Revokes KYC status from the user for the token | Yes | +| `GET` | `/api/v1/tokens/{tokenId}/{username}/info` | Returns token information and status for the specified user | Yes | +| `GET` | `/api/v1/tokens/{tokenId}/serials` | Returns the serial numbers for the specified token | Yes | + +## Endpoints + +- [Token Listing](token-listing.md) +- [Token Listing (v1)](token-listing-1.md) +- [Associates the User with Token](associates-the-user-with-token.md) +- [Disassociates the User with Token](disassociates-the-user-with-token.md) +- [Freeze Tokens of a User](freeze-tokens-of-a-user.md) +- [Unfreeze Tokens of a User](unfreeze-tokens-of-a-user.md) +- [Grants KYC for the User](grants-kyc-for-the-user.md) +- [Revoke KYC of the User](revoke-kyc-of-the-user.md) +- [User Info for Selected Token](user-info-for-selected-token.md) +- [Returns Token Serials](returns-token-serials.md) diff --git a/docs/guardian/tokens/token-operations/token-apis/associates-the-user-with-token.md b/docs/guardian/tokens/token-operations/token-apis/associates-the-user-with-token.md index 8b9c0d46a2..9d2c0a56d8 100644 --- a/docs/guardian/tokens/token-operations/token-apis/associates-the-user-with-token.md +++ b/docs/guardian/tokens/token-operations/token-apis/associates-the-user-with-token.md @@ -1,48 +1,48 @@ -# Associates the user with token +# Associates the User with Token -### ASSOCIATES USER WITH TOKEN +**`PUT /api/v1/tokens/{tokenId}/associate`** -{% swagger method="put" path="" baseUrl="/tokens/{tokenId}/associate" summary="Associates the user with the provided Hedera token" %} -{% swagger-description %} -Associates the user with the provided Hedera token. Only users with the Installer role are allowed to make the request -{% endswagger-description %} +Associates the calling user with the specified Hedera token. Only users with the Installer (User) role are allowed to make the request. -{% swagger-parameter in="path" name="tokenID" type="String" required="true" %} -Token ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +**Permission:** `Permissions.TOKENS_TOKEN_EXECUTE` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `tokenId` | string | Yes | The internal database ID of the token to associate | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "tokenId": "0.0.5000001", + "associated": true, + "balance": "0", + "hBarBalance": "10", + "frozen": false, + "kyc": false } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | User or token does not exist | +| `422 Unprocessable Entity` | User is not registered | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/token-operations/token-apis/disassociates-the-user-with-token.md b/docs/guardian/tokens/token-operations/token-apis/disassociates-the-user-with-token.md index 3d6ead3fc2..14b4a19709 100644 --- a/docs/guardian/tokens/token-operations/token-apis/disassociates-the-user-with-token.md +++ b/docs/guardian/tokens/token-operations/token-apis/disassociates-the-user-with-token.md @@ -1,48 +1,48 @@ -# Disassociates the user with token +# Disassociates the User with Token -### DISASSOCIATES USER WITH TOKEN +**`PUT /api/v1/tokens/{tokenId}/dissociate`** -{% swagger method="put" path="" baseUrl="/tokens/{tokenId}/dissociate" summary="Disassociate the user with the provided Hedera token" %} -{% swagger-description %} -Disassociates the user with the provided Hedera token. Only users with the Installer role are allowed to make the request. -{% endswagger-description %} +Disassociates the calling user from the specified Hedera token. Only users with the Installer (User) role are allowed to make the request. -{% swagger-parameter in="path" name="tokenID" type="String" required="true" %} -Token ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +**Permission:** `Permissions.TOKENS_TOKEN_EXECUTE` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `tokenId` | string | Yes | The internal database ID of the token to dissociate | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "tokenId": "0.0.5000001", + "associated": false, + "balance": "0", + "hBarBalance": "10", + "frozen": false, + "kyc": false } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | User or token does not exist | +| `422 Unprocessable Entity` | User is not registered | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/token-operations/token-apis/freeze-tokens-of-a-user.md b/docs/guardian/tokens/token-operations/token-apis/freeze-tokens-of-a-user.md index 8ff962b697..ff660b9f2f 100644 --- a/docs/guardian/tokens/token-operations/token-apis/freeze-tokens-of-a-user.md +++ b/docs/guardian/tokens/token-operations/token-apis/freeze-tokens-of-a-user.md @@ -1,66 +1,49 @@ -# Freeze Tokens of a user +# Freeze Tokens of a User -### FREEZE TRANSFER OF TOKENS OF A USER +**`PUT /api/v1/tokens/{tokenId}/{username}/freeze`** -{% swagger method="put" path="" baseUrl="/tokens/{tokenId}/{username}/freeze" summary="Freeze transfers of the specified token for the user" %} -{% swagger-description %} -Freezes transfers of the specified token for the user. Only users with the Standard Registry role are allowed to make the request -{% endswagger-description %} +Freezes transfers of the specified token for the given user. Only users with the Standard Registry role are allowed to make the request. -{% swagger-parameter in="path" name="tokenID" type="String" required="true" %} -Token ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-parameter in="path" name="username" type="String" required="true" %} -Username -{% endswagger-parameter %} +**Permission:** `Permissions.TOKENS_TOKEN_MANAGE` -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/TokenInfo' -} -``` -{% endswagger-response %} +--- -{% swagger-response status="400: Bad Request" description="Bad Request" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +### Path Parameters -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `tokenId` | string | Yes | The internal database ID of the token | +| `username` | string | Yes | The username of the user whose token transfers will be frozen | + +--- + +## Response -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "tokenId": "0.0.5000001", + "associated": true, + "balance": "100", + "hBarBalance": "10", + "frozen": true, + "kyc": true } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | User or token does not exist | +| `422 Unprocessable Entity` | User is not registered | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/token-operations/token-apis/grants-kyc-for-the-user.md b/docs/guardian/tokens/token-operations/token-apis/grants-kyc-for-the-user.md index 4093b0b6a5..0c8c0e64c9 100644 --- a/docs/guardian/tokens/token-operations/token-apis/grants-kyc-for-the-user.md +++ b/docs/guardian/tokens/token-operations/token-apis/grants-kyc-for-the-user.md @@ -1,66 +1,49 @@ -# Grants KYC for the user +# Grants KYC for the User -### GRANTS KYC FLAG FOR THE USER +**`PUT /api/v1/tokens/{tokenId}/{username}/grant-kyc`** -{% swagger method="put" path="" baseUrl="/tokens/{tokenId}/{username}/grant-kyc" summary="Sets the KYC flag for the user." %} -{% swagger-description %} -Sets the KYC flag for the user. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +Sets the KYC flag for the specified user on the given token. Only users with the Standard Registry role are allowed to make the request. -{% swagger-parameter in="path" name="tokenID" type="String" required="true" %} -Token ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-parameter in="path" name="username" type="String" required="true" %} -Username -{% endswagger-parameter %} +**Permission:** `Permissions.TOKENS_TOKEN_MANAGE` -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/TokenInfo' -} -``` -{% endswagger-response %} +--- -{% swagger-response status="400: Bad Request" description="Bad Request" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +### Path Parameters -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `tokenId` | string | Yes | The internal database ID of the token | +| `username` | string | Yes | The username of the user to grant KYC | + +--- + +## Response -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "tokenId": "0.0.5000001", + "associated": true, + "balance": "0", + "hBarBalance": "10", + "frozen": false, + "kyc": true } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | User or token does not exist | +| `422 Unprocessable Entity` | User is not registered | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/token-operations/token-apis/returns-token-serials.md b/docs/guardian/tokens/token-operations/token-apis/returns-token-serials.md index 9fbdb07be4..751fa05059 100644 --- a/docs/guardian/tokens/token-operations/token-apis/returns-token-serials.md +++ b/docs/guardian/tokens/token-operations/token-apis/returns-token-serials.md @@ -1,39 +1,42 @@ # Returns Token Serials -{% swagger method="get" path="" baseUrl="/tokens/{tokenId}/serials" summary="Return token serials." %} -{% swagger-description %} -Returns token serials of current user. -{% endswagger-description %} +**`GET /api/v1/tokens/{tokenId}/serials`** -{% swagger-parameter in="path" name="tokenId" type="String" required="true" %} -Token Identifier -{% endswagger-parameter %} +Returns the serial numbers of non-fungible token instances owned by the current user for the specified token. -{% swagger-response status="200: OK" description="Token Serials" %} -``` -content: - application/json: - schema: - type: array - items: - type: number -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} +**Permission:** `Permissions.TOKENS_TOKEN_READ` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} +## Request -{% endswagger-response %} +### Path Parameters -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -``` -content: - application/json: - schema: - $ref: '#/components/schemas/InternalServerErrorDTO' +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `tokenId` | string | Yes | The internal database ID of the token | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +[1, 2, 5, 12] ``` -{% endswagger-response %} -{% endswagger %} + +An array of serial numbers (integers) for the non-fungible token instances held by the current user. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | User or token does not exist | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/token-operations/token-apis/revoke-kyc-of-the-user.md b/docs/guardian/tokens/token-operations/token-apis/revoke-kyc-of-the-user.md index d4b1d10685..f807c5e473 100644 --- a/docs/guardian/tokens/token-operations/token-apis/revoke-kyc-of-the-user.md +++ b/docs/guardian/tokens/token-operations/token-apis/revoke-kyc-of-the-user.md @@ -1,66 +1,49 @@ -# Revoke KYC of the user +# Revoke KYC of the User -### UNSETS KYC FLAG FOR THE USER +**`PUT /api/v1/tokens/{tokenId}/{username}/revoke-kyc`** -{% swagger method="put" path="" baseUrl="/tokens/{tokenId}/{username}/revoke-kyc" summary="Unsets the KYC flag for the user." %} -{% swagger-description %} -Unsets the KYC flag for the user. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +Unsets (revokes) the KYC flag for the specified user on the given token. Only users with the Standard Registry role are allowed to make the request. -{% swagger-parameter in="path" name="tokenID" type="String" required="true" %} -Token ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-parameter in="path" name="username" type="String" required="true" %} -Username -{% endswagger-parameter %} +**Permission:** `Permissions.TOKENS_TOKEN_MANAGE` -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/TokenInfo' -} -``` -{% endswagger-response %} +--- -{% swagger-response status="400: Bad Request" description="Bad Request" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +### Path Parameters -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `tokenId` | string | Yes | The internal database ID of the token | +| `username` | string | Yes | The username of the user whose KYC will be revoked | + +--- + +## Response -{% swagger-response status="500: Internal Server Error" description="" %} -```javascript +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "tokenId": "0.0.5000001", + "associated": true, + "balance": "0", + "hBarBalance": "10", + "frozen": false, + "kyc": false } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | User or token does not exist | +| `422 Unprocessable Entity` | User is not registered | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/token-operations/token-apis/token-listing-1.md b/docs/guardian/tokens/token-operations/token-apis/token-listing-1.md index b6ec6a526d..82d7389664 100644 --- a/docs/guardian/tokens/token-operations/token-apis/token-listing-1.md +++ b/docs/guardian/tokens/token-operations/token-apis/token-listing-1.md @@ -1,70 +1,76 @@ # Creation of Token -### CREATION OF A TOKEN +**`POST /api/v1/tokens`** -{% swagger method="post" path="" baseUrl="/tokens" summary="Creates a new token" %} -{% swagger-description %} -Creates a new token. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +Creates a new token on the Hedera network. Only users with the Standard Registry role are allowed to make the request. -{% swagger-parameter in="body" required="true" %} -Object that contains token information -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="201: Created" description="Created" %} -```javascript -{ - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/TokenInfo' -} -``` -{% endswagger-response %} +**Permission:** `Permissions.TOKENS_TOKEN_CREATE` -{% swagger-response status="400: Bad Request" description="Bad Request" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} -``` -{% endswagger-response %} +--- -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request + +### Request Body -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +```json { - // Response + "tokenName": "Example Token", + "tokenSymbol": "EXT", + "tokenType": "fungible", + "decimals": "2", + "initialSupply": "0", + "changeSupply": true, + "enableAdmin": true, + "enableKYC": true, + "enableFreeze": true, + "enableWipe": true } ``` -{% endswagger-response %} -{% swagger-response status="422: Unprocessable Entity" description="Unprocessable Entity" %} -``` -User not registered -``` -{% endswagger-response %} +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `tokenName` | string | Yes | Human-readable name of the token | +| `tokenSymbol` | string | Yes | Short symbol for the token | +| `tokenType` | string | Yes | Type of token: `fungible` or `non-fungible` | +| `decimals` | string | No | Number of decimal places (fungible tokens only) | +| `initialSupply` | string | No | Initial token supply | +| `changeSupply` | boolean | No | Whether the supply can be changed | +| `enableAdmin` | boolean | No | Whether admin key is enabled | +| `enableKYC` | boolean | No | Whether KYC key is enabled | +| `enableFreeze` | boolean | No | Whether freeze key is enabled | +| `enableWipe` | boolean | No | Whether wipe key is enabled | -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +```json +[ + { + "tokenId": "0.0.5000001", + "tokenName": "Example Token", + "tokenSymbol": "EXT", + "tokenType": "fungible", + "decimals": "2", + "initialSupply": "0", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "policies": [], + "policyIds": [] + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | User is not registered | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/token-operations/token-apis/token-listing.md b/docs/guardian/tokens/token-operations/token-apis/token-listing.md index 82e8539eb1..1e2abb71f4 100644 --- a/docs/guardian/tokens/token-operations/token-apis/token-listing.md +++ b/docs/guardian/tokens/token-operations/token-apis/token-listing.md @@ -1,55 +1,62 @@ # Token Listing -### DISPLAYS ALL TOKENS - -{% swagger method="get" path="" baseUrl="/tokens" summary="Return a list of tokens" %} -{% swagger-description %} -Returns all tokens. For the Standard Registry role it returns only the list of tokens, for other users it also returns token balances as well as the KYC, Freeze, and Association statuses. Not allowed for the Auditor role. -{% endswagger-description %} - -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - application/json: - schema: - type: array - items: - allOf: - - $ref: '#/components/schemas/TokenInfo' - - type: object - properties: - policies: - type: array - items: - type: string -} -``` -{% endswagger-response %} +**`GET /api/v1/tokens`** -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +Returns all tokens. For the Standard Registry role it returns only the list of tokens; for other users it also returns token balances as well as the KYC, Freeze, and Association statuses. Not allowed for the Auditor role. -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} - -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.TOKENS_TOKEN_READ` + +--- + +## Request + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `pageIndex` | number | No | 0 | Zero-based page index | +| `pageSize` | number | No | 20 | Items per page | +| `policyId` | string | No | — | Filter tokens associated with this policy ID | +| `status` | string | No | — | Token status filter: `Associated` or `All` | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +[ + { + "tokenId": "0.0.5000001", + "tokenName": "Example Token", + "tokenSymbol": "EXT", + "tokenType": "fungible", + "decimals": "2", + "initialSupply": "0", + "adminId": "0.0.4532001", + "changeSupply": true, + "enableAdmin": true, + "enableKYC": true, + "enableFreeze": true, + "enableWipe": true, + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "policies": ["iREC 3 (1.0.0)"], + "policyIds": ["63e3e5e8a01b3c001234abcd"] + } +] ``` -{% endswagger-response %} -{% endswagger %} + +The response includes an `X-Total-Count` header with the total number of tokens. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/token-operations/token-apis/unfreeze-tokens-of-a-user.md b/docs/guardian/tokens/token-operations/token-apis/unfreeze-tokens-of-a-user.md index 7e1040f71c..50b6240ed6 100644 --- a/docs/guardian/tokens/token-operations/token-apis/unfreeze-tokens-of-a-user.md +++ b/docs/guardian/tokens/token-operations/token-apis/unfreeze-tokens-of-a-user.md @@ -1,66 +1,49 @@ -# UnFreeze Tokens of a user +# Unfreeze Tokens of a User -### UNFREEZE TRANSFER OF TOKENS OF A USER +**`PUT /api/v1/tokens/{tokenId}/{username}/unfreeze`** -{% swagger method="put" path="" baseUrl="/tokens/{tokenId}/{username}/unfreeze" summary="Unfreezes transfers of the specified token for the user" %} -{% swagger-description %} -Unfreezes transfers of the specified token for the user. Only users with the Standard Registry role are allowed to make the request -{% endswagger-description %} +Unfreezes transfers of the specified token for the given user. Only users with the Standard Registry role are allowed to make the request. -{% swagger-parameter in="path" name="tokenID" type="String" required="true" %} -Token ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-parameter in="path" name="username" type="String" required="true" %} -Username -{% endswagger-parameter %} +**Permission:** `Permissions.TOKENS_TOKEN_MANAGE` -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/TokenInfo' -} -``` -{% endswagger-response %} +--- -{% swagger-response status="400: Bad Request" description="Bad Request" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +### Path Parameters -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `tokenId` | string | Yes | The internal database ID of the token | +| `username` | string | Yes | The username of the user whose token transfers will be unfrozen | + +--- + +## Response -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "tokenId": "0.0.5000001", + "associated": true, + "balance": "100", + "hBarBalance": "10", + "frozen": false, + "kyc": true } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | User or token does not exist | +| `422 Unprocessable Entity` | User is not registered | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/tokens/token-operations/token-apis/user-info-for-selected-token.md b/docs/guardian/tokens/token-operations/token-apis/user-info-for-selected-token.md index 7bc9b2a616..5291e69494 100644 --- a/docs/guardian/tokens/token-operations/token-apis/user-info-for-selected-token.md +++ b/docs/guardian/tokens/token-operations/token-apis/user-info-for-selected-token.md @@ -1,66 +1,58 @@ -# User Info for selected token +# User Info for Selected Token -### DISPLAYS USER INFORMATION FOR SELECTED TOKEN +**`GET /api/v1/tokens/{tokenId}/{username}/info`** -{% swagger method="get" path="" baseUrl="/tokens/{tokenId}/{username}/info" summary="Returns User information" %} -{% swagger-description %} -Returns user information for the selected token. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +Returns token status information for a specific user on the given token, including KYC, freeze, and association status. Only users with the Standard Registry role are allowed to make the request. -{% swagger-parameter in="path" name="tokenID" type="String" required="true" %} -Token ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-parameter in="path" name="username" required="true" %} -Username -{% endswagger-parameter %} +**Permission:** `Permissions.TOKENS_TOKEN_MANAGE` -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/TokenInfo' -} -``` -{% endswagger-response %} +--- -{% swagger-response status="400: Bad Request" description="Bad Request" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +### Path Parameters -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `tokenId` | string | Yes | The internal database ID of the token | +| `username` | string | Yes | The username of the user to retrieve token info for | + +--- -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +## Response + +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "tokenId": "0.0.5000001", + "associated": true, + "balance": "50", + "hBarBalance": "10", + "frozen": false, + "kyc": true } ``` -{% endswagger-response %} -{% endswagger %} + +| Field | Type | Description | +|-------|------|-------------| +| `tokenId` | string | Hedera token ID | +| `associated` | boolean | Whether the user is associated with the token | +| `balance` | string | User's token balance | +| `hBarBalance` | string | User's HBAR balance | +| `frozen` | boolean | Whether the user's token transfers are frozen | +| `kyc` | boolean | Whether the user has passed KYC for this token | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | User or token does not exist | +| `422 Unprocessable Entity` | User is not registered | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/guardian/users/ai-search/ai-search-apis/README.md b/docs/guardian/users/ai-search/ai-search-apis/README.md index b852ee1350..30dd49f803 100644 --- a/docs/guardian/users/ai-search/ai-search-apis/README.md +++ b/docs/guardian/users/ai-search/ai-search-apis/README.md @@ -1,2 +1,17 @@ # AI Search APIs +Endpoints for Guardian's AI-powered policy suggestion and natural language search capabilities. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `POST` | `/api/v1/ai-suggestions` | Returns AI-generated policy recommendations for a given query | Yes | +| `PUT` | `/api/v1/ai-suggestions/rebuild-vector` | Rebuilds the AI vector index from current policy data | Yes | + +## Endpoints + +- [Returns AI Search Response](returns-response.md) +- [Rebuilds Vector Based on Policy Data](rebuilds-vector-based-on-policy-data.md) diff --git a/docs/guardian/users/bottom-up-data-traceability/related-apis/README.md b/docs/guardian/users/bottom-up-data-traceability/related-apis/README.md index fb7c246629..457045431b 100644 --- a/docs/guardian/users/bottom-up-data-traceability/related-apis/README.md +++ b/docs/guardian/users/bottom-up-data-traceability/related-apis/README.md @@ -1,2 +1,37 @@ -# Related APIs +# Bottom-Up Data Traceability APIs +Endpoints for creating and managing policy statistics definitions and assessments. Statistics definitions specify rules for evaluating documents; assessments apply those rules to produce verifiable results. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `GET` | `/api/v1/policy-statistics` | Returns all statistics definitions | Yes | +| `POST` | `/api/v1/policy-statistics` | Creates a new statistics definition | Yes | +| `GET` | `/api/v1/policy-statistics/{definitionId}` | Returns a statistics definition by ID | Yes | +| `PUT` | `/api/v1/policy-statistics/{definitionId}` | Updates a statistics definition | Yes | +| `DELETE` | `/api/v1/policy-statistics/{definitionId}` | Deletes a statistics definition | Yes | +| `POST` | `/api/v1/policy-statistics/{definitionId}/publish` | Publishes a statistics definition | Yes | +| `GET` | `/api/v1/policy-statistics/{definitionId}/relationships` | Returns linked schemas and policies | Yes | +| `GET` | `/api/v1/policy-statistics/{definitionId}/documents` | Returns documents conforming to the definition rules | Yes | +| `GET` | `/api/v1/policy-statistics/{definitionId}/assessments` | Returns all assessments for a definition | Yes | +| `POST` | `/api/v1/policy-statistics/{definitionId}/assessments` | Creates a new assessment | Yes | +| `GET` | `/api/v1/policy-statistics/{definitionId}/assessments/{assessmentId}` | Returns an assessment by ID | Yes | +| `GET` | `/api/v1/policy-statistics/{definitionId}/assessments/{assessmentId}/relationships` | Returns all VC documents related to an assessment | Yes | + +## Endpoints + +- [Get the List of Statistics Definitions](get-the-list-of-statistics-definitions.md) +- [Create New Statistics Definition](create-new-statistics-definition.md) +- [Retrieve Details of the Statistics Definition by ID](retrieve-details-of-the-statistics-definition-by-id.md) +- [Update Configuration of the Statistics Definition by ID](update-configuration-of-the-statistics-definition-by-id.md) +- [Delete the Statistics Definition by ID](delete-the-statistics-definition-by-id.md) +- [Publish Statistics Definition by ID](publish-statistics-definition-by-id.md) +- [Retrieve the List of Linked Schemas and Policy](retrieve-the-list-of-linked-schemas-and-policy.md) +- [Retrieve the List of All Documents Conforming the Rules](retrieve-the-list-of-all-documents-conforming-the-rules-of-the-statistics-definition..md) +- [Retrieve the List of Existing Statistics Assessments](retrieve-the-list-of-existing-statistics-assessment.md) +- [Create a New Statistics Assessment](create-a-new-statistics-assessment-based-on-the-statistics-definition.md) +- [Retrieve the Statistics Assessment by ID](retrieve-the-statistics-assessment-by-id.md) +- [Retrieve All VC Documents Related to the Statistics Assessment](retrieve-all-vc-documents-related-to-the-statistics-assessment.md) diff --git a/docs/guardian/users/guided-search-of-methodologies/search-apis/README.md b/docs/guardian/users/guided-search-of-methodologies/search-apis/README.md index 87b2fcc690..b61e85ee63 100644 --- a/docs/guardian/users/guided-search-of-methodologies/search-apis/README.md +++ b/docs/guardian/users/guided-search-of-methodologies/search-apis/README.md @@ -1,2 +1,17 @@ -# Search APIs +# Guided Search APIs +Endpoints for discovering and filtering Guardian policies and methodologies by category and properties. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `GET` | `/api/v1/policies/categories` | Returns a list of all policy categories | Yes | +| `POST` | `/api/v1/policies/filtered-policies` | Returns policies best suited for specified filter parameters | Yes | + +## Endpoints + +- [Retrieves List of All Categories](retrieves-list-of-all-categories.md) +- [List of Policies Best Suited for Given Parameters](list-of-policies-that-are-best-suited-for-given-parameters.md) diff --git a/docs/guardian/users/user-operations/account-apis/README.md b/docs/guardian/users/user-operations/account-apis/README.md index ab593ee29e..8e65f4dd0e 100644 --- a/docs/guardian/users/user-operations/account-apis/README.md +++ b/docs/guardian/users/user-operations/account-apis/README.md @@ -1,2 +1,27 @@ # Account APIs +Endpoints for user registration, authentication, and account management in Guardian. + +**Authentication:** Bearer token required for protected endpoints (`Authorization: Bearer `). Registration and login endpoints are unauthenticated. + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `POST` | `/api/v1/accounts/register` | Register a new user account | No | +| `POST` | `/api/v1/accounts/login` | Login and obtain a Bearer token | No | +| `GET` | `/api/v1/accounts/session` | Returns the current authenticated user session | Yes | +| `GET` | `/api/v1/accounts` | Returns all users except Standard Registries and Auditors | Yes | +| `GET` | `/api/v1/accounts/standard-registries` | Returns all Standard Registry accounts | Yes | +| `GET` | `/api/v1/accounts/balance` | Returns balance for the current user | Yes | + +## Endpoints + +- [Authentication Process](authentication-process.md) +- [Registering New Account](registering-new-account.md) +- [User Login](user-login.md) +- [User Session](user-session.md) +- [User Listing](user-listing-except-root-authority-and-auditor.md) +- [Returns All Root Authorities](returns-all-root-authorities.md) +- [User Balance](user-balance.md) +- [Returns Access Token](returns-access-token.md) diff --git a/docs/guardian/users/user-operations/profile-apis/README.md b/docs/guardian/users/user-operations/profile-apis/README.md index dd213e1ed0..5b04a54c54 100644 --- a/docs/guardian/users/user-operations/profile-apis/README.md +++ b/docs/guardian/users/user-operations/profile-apis/README.md @@ -1,2 +1,21 @@ # Profile APIs +Endpoints for viewing and updating user profile credentials and account information in Guardian. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +--- + +| Method | Endpoint | Description | Auth Required | +|---|---|---|---| +| `GET` | `/api/v1/profiles/{username}` | Returns the DID document and Hedera account information for the user | Yes | +| `PUT` | `/api/v1/profiles/{username}` | Sets Hedera credentials and creates a DID for the user | Yes | +| `PUT` | `/api/v1/profiles/push/{username}` | Sets Hedera credentials asynchronously | Yes | +| `GET` | `/api/v1/profiles/{username}/balance` | Returns the Hedera account balance for the user | Yes | + +## Endpoints + +- [User Account Information](user-account-information.md) +- [Setting User Credentials](setting-user-credentials.md) +- [Setting User Credentials Asynchronously](setting-user-credentials-asynchronously.md) +- [User Account Balance](user-account-balance.md) diff --git a/docs/logs-apis/README.md b/docs/logs-apis/README.md new file mode 100644 index 0000000000..654f21922a --- /dev/null +++ b/docs/logs-apis/README.md @@ -0,0 +1,25 @@ +# Logs APIs + +**Base URL:** `/api/v1/logs` + +These endpoints provide access to Guardian system logs for operational monitoring and debugging, including filtered log retrieval and attribute discovery. + +**Authentication:** All endpoints require a valid JWT Bearer token (`Authorization: Bearer `). Obtain a token via `POST /accounts/login`. Permission `LOG_LOG_READ` is required for all endpoints. + +--- + +## Endpoints + +| Method | Endpoint | Description | Auth Required | +|--------|----------|-------------|---------------| +| POST | `/logs` | Return a filtered, paginated list of system logs | Yes | +| GET | `/logs/attributes` | Return a list of known log attribute values | Yes | +| GET | `/logs/seq` | Return the URL of the Seq log aggregation server | Yes | + +--- + +## Endpoint Details + +* [Returning Logs](returning-logs.md) +* [Returning Log Attributes](returning-log-attributes.md) +* [Returns Seq URL](returns-seq-url.md) diff --git a/docs/logs-apis/returning-log-attributes.md b/docs/logs-apis/returning-log-attributes.md index 9c97b7b08e..95255ce5ce 100644 --- a/docs/logs-apis/returning-log-attributes.md +++ b/docs/logs-apis/returning-log-attributes.md @@ -1,51 +1,40 @@ # Returning Log Attributes -## RETURNS LOGS ATTRIBUTES - -{% swagger method="get" path="" baseUrl="/logs/attributes" summary="Returns logs attributes" %} -{% swagger-description %} -Returns logs attributes. For users with the Standard Registry role only. -{% endswagger-description %} - -{% swagger-parameter in="query" name="name" type="String" required="true" %} -Part of the name -{% endswagger-parameter %} - -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - application/json: - schema: - type: array - items: - type: string -} -``` -{% endswagger-response %} +**`GET /logs/attributes`** -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +Returns a list of log source attribute names, optionally filtered by a name substring. For Standard Registry users only. -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} - -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript -{ - application/json: - schema: - $ref: '#/components/schemas/Error' -} +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.LOG_LOG_READ` + +--- + +## Request + +### Query Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `name` | string | No | Substring to search within attribute names | +| `existingAttributes` | string[] | No | Attributes already selected (excluded from results) | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +["API_GATEWAY", "WORKER", "GUARDIAN_SERVICE"] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/logs-apis/returning-logs.md b/docs/logs-apis/returning-logs.md index e9dceb5925..5f455078ad 100644 --- a/docs/logs-apis/returning-logs.md +++ b/docs/logs-apis/returning-logs.md @@ -1,95 +1,78 @@ # Returning Logs -## RETURNS LOGS +**`POST /logs/`** -{% swagger method="post" path="" baseUrl="/logs" summary="Returns logs." %} -{% swagger-description %} -Returns logs. For users with the Standard Registry role only. -{% endswagger-description %} +Returns a paginated list of system logs filtered by the provided criteria. For Standard Registry users only. -{% swagger-parameter in="body" type="String" name="type" required="true" %} -Type of Log -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-parameter in="body" name="startDate" type="String" required="true" %} -Start Date -{% endswagger-parameter %} +**Permission:** `Permissions.LOG_LOG_READ` -{% swagger-parameter in="body" name="endDate" type="String" required="true" %} -End Date -{% endswagger-parameter %} +--- -{% swagger-parameter in="body" name="attributes" type="Array" required="true" %} -Attributes -{% endswagger-parameter %} +## Request -{% swagger-parameter in="body" name="items" type="String" required="true" %} -Items -{% endswagger-parameter %} +### Request Body -{% swagger-parameter in="body" name="message" type="String" required="true" %} -Log Message -{% endswagger-parameter %} +```json +{ + "type": "INFO", + "startDate": "2024-01-01T00:00:00.000Z", + "endDate": "2024-12-31T23:59:59.999Z", + "attributes": ["API_GATEWAY"], + "message": "policy", + "pageIndex": 0, + "pageSize": 20, + "sortDirection": "DESC" +} +``` -{% swagger-parameter in="body" name="pageSize" type="Number" required="true" %} -Size of the Page -{% endswagger-parameter %} +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `type` | string | No | Log level filter: `INFO`, `WARN`, `ERROR` | +| `startDate` | string (ISO 8601) | No | Filter logs after this date | +| `endDate` | string (ISO 8601) | No | Filter logs before this date | +| `attributes` | string[] | No | Filter by log source attributes (e.g. `["API_GATEWAY"]`) | +| `message` | string | No | Case-insensitive substring search within log messages | +| `pageIndex` | number | No | Zero-based page index (default: `0`) | +| `pageSize` | number | No | Items per page | +| `sortDirection` | string | No | Sort order: `ASC` or `DESC` | -{% swagger-parameter in="body" name="pageIndex" type="Number" required="true" %} -Index of page -{% endswagger-parameter %} +--- -{% swagger-parameter in="body" name="sortDirection" type="String" required="true" %} -enum: [ASC, DESC] -{% endswagger-parameter %} +## Response -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - application/json: - schema: - totalCount: - type: number - logs: - type: object - properties: - type: - type: string - datetime: - type: string - message: - type: string - attributes: - type: array - items: - type: string -} -``` -{% endswagger-response %} +### Success Response -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +**Status:** `200 OK` -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +```json { - // Response + "totalCount": 142, + "logs": [ + { + "type": "INFO", + "datetime": "2024-06-01T12:34:56.789Z", + "message": "Policy published successfully", + "attributes": ["API_GATEWAY"] + } + ] } ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript -{ - application/json: - schema: - $ref: '#/components/schemas/Error' -} -``` -{% endswagger-response %} -{% endswagger %} +| Field | Type | Description | +|-------|------|-------------| +| `totalCount` | number | Total number of matching log entries | +| `logs` | array | Array of log entries | +| `logs[].type` | string | Log level | +| `logs[].datetime` | string | Timestamp of the log entry | +| `logs[].message` | string | Log message text | +| `logs[].attributes` | string[] | Source attributes | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/logs-apis/returns-seq-url.md b/docs/logs-apis/returns-seq-url.md new file mode 100644 index 0000000000..5d5cd2d57e --- /dev/null +++ b/docs/logs-apis/returns-seq-url.md @@ -0,0 +1,45 @@ +# Returns Seq URL + +**`GET /logs/seq`** + +Returns the URL to the Seq log aggregation store, if configured. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.LOG_LOG_READ` + +--- + +## Request + +No request body or parameters required. + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "seq_url": "http://localhost:5341" +} +``` + +Returns `null` for `seq_url` if Seq is not configured. + +```json +{ + "seq_url": null +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/policy-creation-using-the-guardian-apis/README.md b/docs/policy-creation-using-the-guardian-apis/README.md new file mode 100644 index 0000000000..8d29a11d85 --- /dev/null +++ b/docs/policy-creation-using-the-guardian-apis/README.md @@ -0,0 +1,61 @@ +# Policy Creation APIs + +**Base URL:** `/api/v1` + +These APIs enable Standard Registry users to create, configure, publish, and manage Guardian policies. Users and auditors can also interact with running policies via block and group endpoints. + +**Authentication:** All endpoints require a valid JWT Bearer token (`Authorization: Bearer `). Obtain a token via `POST /accounts/login`. + +See [Prerequisite Steps](prerequesite-steps.md) before getting started. + +--- + +## Endpoints + +| Method | Endpoint | Description | Auth Required | +|--------|----------|-------------|---------------| +| GET | `/policies` | List all policies | Yes | +| POST | `/policies` | Create a new policy | Yes | +| GET | `/policies/{policyId}` | Get policy configuration | Yes | +| PUT | `/policies/{policyId}` | Update policy configuration | Yes | +| PUT | `/policies/{policyId}/publish` | Publish a policy | Yes | +| POST | `/policies/validate` | Validate policy configuration | Yes | +| GET | `/policies/{policyId}/blocks` | Get root policy block data | Yes | +| GET | `/policies/{policyId}/blocks/{uuid}` | Get block data by UUID | Yes | +| POST | `/policies/{policyId}/blocks/{uuid}` | Send data to a block | Yes | +| GET | `/policies/{policyId}/tag/{tagName}` | Get block ID by tag | Yes | +| GET | `/policies/{policyId}/tag/{tagName}/blocks` | Get block data by tag | Yes | +| POST | `/policies/{policyId}/tag/{tagName}/blocks` | Send data to block by tag | Yes | +| GET | `/policies/{policyId}/groups` | List groups for the current user | Yes | +| POST | `/policies/{policyId}/groups` | Set the active group | Yes | +| GET | `/policies/{policyId}/export/file` | Export policy as zip | Yes | +| GET | `/policies/{policyId}/export/message` | Export policy message ID | Yes | +| POST | `/policies/import/file` | Import policy from zip | Yes | +| POST | `/policies/import/message` | Import policy from IPFS | Yes | +| POST | `/policies/import/message/preview` | Preview policy from IPFS | Yes | + +--- + +## Endpoint Details + +* [Prerequisite Steps](prerequesite-steps.md) — Authentication and account setup +* [Policy Listing](policy-listing.md) — `GET /policies` +* [Creation of a Policy](creation-of-a-policy.md) — `POST /policies` +* [Retrieves Policy Configuration](retrieves-policy-configuration.md) — `GET /policies/{policyId}` +* [Updates Policy Configuration](updates-policy-configuration.md) — `PUT /policies/{policyId}` +* [Publish a Policy](publish-a-policy.md) — `PUT /policies/{policyId}/publish` +* [Policy Validation](policy-validation.md) — `POST /policies/validate` +* [Retrieval of Data from Root Policy Block](retrieval-of-data-from-root-policy-block.md) — `GET /policies/{policyId}/blocks` +* [Request Block Data](request-block-data.md) — `GET /policies/{policyId}/blocks/{uuid}` +* [Sends Data to Specified Block](sends-data-to-specified-block.md) — `POST /policies/{policyId}/blocks/{uuid}` +* [Returns Block ID by Tag](returns-block-id-by-tag.md) — `GET /policies/{policyId}/tag/{tagName}` +* [Retrieves Block Data by Tag](retrieves-block-data-by-tag.md) — `GET /policies/{policyId}/tag/{tagName}/blocks` +* [Sends Data to Specified Block by Tag](sends-data-to-specified-block-by-tag.md) — `POST /policies/{policyId}/tag/{tagName}/blocks` +* [Returns List of Groups of a Particular User](returns-list-of-groups-of-a-particular-user.md) — `GET /policies/{policyId}/groups` +* [Make the Selected Group Active](make-the-selected-group-active.md) — `POST /policies/{policyId}/groups` +* [Export to Zip File](export-to-zip-file.md) — `GET /policies/{policyId}/export/file` +* [Exporting Message ID](exporting-message-id.md) — `GET /policies/{policyId}/export/message` +* [Import a Policy](import-a-policy.md) — `POST /policies/import/message` +* [Import from Zip File](import-from-zip-file.md) — `POST /policies/import/file` +* [Policy Preview from IPFS](policy-preview-from-ipfs.md) — `POST /policies/import/message/preview` +* [Dynamic Policy Fields Guide](dynamic-policy-fields.md) — Dynamic field configuration reference diff --git a/docs/policy-creation-using-the-guardian-apis/creation-of-a-policy.md b/docs/policy-creation-using-the-guardian-apis/creation-of-a-policy.md index 085d571a03..b3233d0acc 100644 --- a/docs/policy-creation-using-the-guardian-apis/creation-of-a-policy.md +++ b/docs/policy-creation-using-the-guardian-apis/creation-of-a-policy.md @@ -1,44 +1,71 @@ # Creation of a Policy -### **POLICY CREATION** +**`POST /api/v1/policies`** -{% swagger method="post" path="" baseUrl="/policies" summary="Creates a new policy" %} -{% swagger-description %} -Creates a new policy. Only users with the Standard Registry role are allowed to make the request -{% endswagger-description %} +Creates a new policy. Only users with the Standard Registry role are allowed to make the request. -{% swagger-parameter in="body" type="Object" required="true" %} -Object that contains policy configuration. -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="201: Created" description="Created" %} +**Permission:** `Permissions.POLICIES_POLICY_CREATE` -{% endswagger-response %} +--- -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request + +### Request Body -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +```json { - // Response + "name": "iREC Policy", + "version": "1.0.0", + "description": "iREC renewable energy certificate policy", + "topicDescription": "iREC policy topic", + "config": {}, + "policyRoles": ["INSTALLER"], + "policyTopics": [], + "policyTokens": [], + "policyGroups": [] } ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal server error" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | Yes | Human-readable policy name | +| `version` | string | No | Semantic version string (e.g. `1.0.0`) | +| `description` | string | No | Short description of the policy | +| `topicDescription` | string | No | Description for the Hedera topic | +| `config` | object | No | Policy block configuration tree | +| `policyRoles` | array | No | List of role names defined by this policy | +| `policyTopics` | array | No | Topic configuration | +| `policyTokens` | array | No | Token configuration | +| `policyGroups` | array | No | Group configuration | + +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +Returns the updated list of all policies for the authenticated user. + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "name": "iREC Policy", + "version": "1.0.0", + "status": "DRAFT", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001" + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/policy-creation-using-the-guardian-apis/export-to-zip-file.md b/docs/policy-creation-using-the-guardian-apis/export-to-zip-file.md index 3f1ffbc889..2dee4695bd 100644 --- a/docs/policy-creation-using-the-guardian-apis/export-to-zip-file.md +++ b/docs/policy-creation-using-the-guardian-apis/export-to-zip-file.md @@ -1,51 +1,42 @@ -# Export to zip file - -### POLICY EXPORT FROM .ZIP - -{% swagger method="get" path="" baseUrl="/policies/{policyId}/export/file" summary="Return policy and its artifacts in a zip file format for the specified policy" %} -{% swagger-description %} -Returns a zip file containing the published policy and all associated artifacts, i.e. schemas and VCs. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} - -{% swagger-parameter in="path" name="policyID" type="String" required="true" %} -Selected policy ID -{% endswagger-parameter %} - -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/ExportPolicy' -} -``` -{% endswagger-response %} - -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} - -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} - -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} -``` -{% endswagger-response %} -{% endswagger %} +# Export to Zip File + +**`GET /policies/{policyId}/export/file`** + +Returns the policy and all associated artifacts (schemas, VCs) as a zip file. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.POLICIES_POLICY_READ` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `policyId` | string | Yes | The policy ID (MongoDB ObjectId, e.g. `63e3e5e8a01b3c001234abcd`) | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +Returns a binary zip file. + +**Headers:** +- `Content-Disposition: attachment; filename=` +- `Content-Type: application/zip` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Policy not found | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/policy-creation-using-the-guardian-apis/exporting-message-id.md b/docs/policy-creation-using-the-guardian-apis/exporting-message-id.md index 033014c10f..0e0cb45005 100644 --- a/docs/policy-creation-using-the-guardian-apis/exporting-message-id.md +++ b/docs/policy-creation-using-the-guardian-apis/exporting-message-id.md @@ -1,51 +1,47 @@ # Exporting Message ID -### EXPORTING MESSAGE ID FOR A POLICY +**`GET /policies/{policyId}/export/message`** -{% swagger method="get" path="" baseUrl="/policies/{policyId}/export/message" summary="Return Hedera message ID for the specified published policy" %} -{% swagger-description %} -Returns the Hedera message ID for the specified policy published onto IPFS. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +Returns the Hedera message ID for the specified published policy. -{% swagger-parameter in="path" name="policyID" type="String" required="true" %} -Selected policy ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/ExportPolicy' -} -``` -{% endswagger-response %} +**Permission:** `Permissions.POLICIES_POLICY_READ` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `policyId` | string | Yes | The policy ID (MongoDB ObjectId, e.g. `63e3e5e8a01b3c001234abcd`) | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "id": "63e3e5e8a01b3c001234abcd", + "name": "iREC Policy", + "description": "iREC standard policy", + "version": "1.0.0", + "messageId": "1680000000.000000001", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001" } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Policy not found | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/policy-creation-using-the-guardian-apis/import-a-policy.md b/docs/policy-creation-using-the-guardian-apis/import-a-policy.md index 6438812d98..1f10959a0d 100644 --- a/docs/policy-creation-using-the-guardian-apis/import-a-policy.md +++ b/docs/policy-creation-using-the-guardian-apis/import-a-policy.md @@ -1,53 +1,64 @@ # Import a Policy from IPFS -### IMPORT A POLICY +**`POST /policies/import/message`** -{% swagger method="post" path="" baseUrl="policies/import/message" summary="Imports new policy from IPFS." %} -{% swagger-description %} -Imports new policy and all associated artifacts from IPFS into the local DB. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +Imports a new policy and all associated artifacts from IPFS into the local database using the Hedera message ID. -{% swagger-parameter in="body" type="Object" required="true" name="schema" %} -Object that contains the identifier of the Hedera message which contains the IPFS CID of the Policy -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="201: Created" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/PolicyConfig' -} -``` -{% endswagger-response %} +**Permission:** `Permissions.POLICIES_POLICY_CREATE` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- + +## Request + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `versionOfTopicId` | string | No | — | The topic ID of the policy version to associate | +| `demo` | boolean | No | false | Import the policy in demo mode | +| `originalTracking` | boolean | No | false | Save the original state of the policy | + +### Request Body -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +```json { - // Response + "messageId": "1680000000.000000001" } ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal server error" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `messageId` | string | Yes | The Hedera message ID that contains the IPFS CID of the policy | + +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "name": "iREC Policy", + "version": "1.0.0", + "status": "DRAFT", + "topicId": "0.0.4532001" + } +] ``` -{% endswagger-response %} -{% endswagger %} + +Returns the full list of policies after import. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Message ID is missing or invalid | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/policy-creation-using-the-guardian-apis/import-from-zip-file.md b/docs/policy-creation-using-the-guardian-apis/import-from-zip-file.md index 5b24b8e8ca..5c2bd4e8f3 100644 --- a/docs/policy-creation-using-the-guardian-apis/import-from-zip-file.md +++ b/docs/policy-creation-using-the-guardian-apis/import-from-zip-file.md @@ -1,53 +1,57 @@ -# Import from zip file - -### POLICY IMPORT FROM .ZIP - -{% swagger method="post" path="" baseUrl="/policies/import/file" summary="Imports new policy from a zip file" %} -{% swagger-description %} -Imports new policy and all associated artifacts, such as schemas and VCs, from the provided zip file into the local DB. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} - -{% swagger-parameter in="body" required="true" %} -A zip file that contains the policy and associated schemas and VCs to be imported -{% endswagger-parameter %} - -{% swagger-response status="201: Created" description="Created" %} -```javascript -{ - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/PolicyConfig' -} -``` -{% endswagger-response %} +# Import from Zip File -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +**`POST /policies/import/file`** -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} - -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} +Imports a new policy and all associated artifacts (schemas, VCs) from the provided zip file into the local database. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.POLICIES_POLICY_CREATE` + +--- + +## Request + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `versionOfTopicId` | string | No | — | The topic ID of the policy version to associate | +| `demo` | boolean | No | false | Import the policy in demo mode | + +### Request Body + +The request body must be the raw binary content of a `.zip` file exported from Guardian. + +**Content-Type:** `application/octet-stream` + +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "name": "iREC Policy", + "version": "1.0.0", + "status": "DRAFT", + "topicId": "0.0.4532001" + } +] ``` -{% endswagger-response %} -{% endswagger %} + +Returns the full list of policies after import. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Invalid zip file content | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/policy-creation-using-the-guardian-apis/make-the-selected-group-active.md b/docs/policy-creation-using-the-guardian-apis/make-the-selected-group-active.md index 2ec7c4581a..71c4eb4e9d 100644 --- a/docs/policy-creation-using-the-guardian-apis/make-the-selected-group-active.md +++ b/docs/policy-creation-using-the-guardian-apis/make-the-selected-group-active.md @@ -1,46 +1,57 @@ -# Make the selected Group active +# Make the Selected Group Active -{% swagger method="post" path="" baseUrl="/policies/{policyId}/groups" summary="Makes the selected group active." %} -{% swagger-description %} -Makes the selected group active. if UUID is not set then returns the user to the default state. -{% endswagger-description %} +**`POST /policies/{policyId}/groups`** -{% swagger-parameter in="body" required="true" name="uuid" type="String" %} -Selected Group -{% endswagger-parameter %} +Makes the selected group active for the current user. If no UUID is provided, the user is returned to the default state. -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +**Permission:** `Permissions.POLICIES_POLICY_EXECUTE` or `Permissions.POLICIES_POLICY_MANAGE` + +--- + +## Request + +### Path Parameters -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `policyId` | string | Yes | The policy ID (MongoDB ObjectId, e.g. `63e3e5e8a01b3c001234abcd`) | + +### Request Body + +```json { - // Response + "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal Sever Error" %} -```javascript +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `uuid` | string | No | UUID of the group to make active. Omit to reset to default state | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "role": "INSTALLER", + "active": true } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Policy or group not found | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/policy-creation-using-the-guardian-apis/policy-listing.md b/docs/policy-creation-using-the-guardian-apis/policy-listing.md index 2ed4c127b1..71a3bf8f6f 100644 --- a/docs/policy-creation-using-the-guardian-apis/policy-listing.md +++ b/docs/policy-creation-using-the-guardian-apis/policy-listing.md @@ -1,69 +1,54 @@ # Policy Listing -### **POLICY LISTING** - -{% swagger method="get" path="" baseUrl="/policies" summary="Return a list of all policies" %} -{% swagger-description %} -Returns all policies. Only users with the Standard Registry and Installer role are allowed to make the request -{% endswagger-description %} - -{% swagger-parameter in="query" name="pageIndex" type="Integer" required="true" %} -The number of pages to skip before starting to collect the result set -{% endswagger-parameter %} - -{% swagger-parameter in="query" name="pageSize" type="Integer" required="true" %} -The numbers of items to return -{% endswagger-parameter %} - -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - headers: - x-total-count: - schema: - type: integer - description: Total items in the collection. - content: - application/json: - schema: - type: array - items: - allOf: - - $ref: '#/components/schemas/PolicyConfig' - - type: object - properties: - userRoles: - type: array - items: - type: string -} -``` -{% endswagger-response %} +**`GET /api/v1/policies`** -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +Returns all policies accessible to the authenticated user. -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} - -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.POLICIES_POLICY_READ`, `Permissions.POLICIES_POLICY_EXECUTE`, `Permissions.POLICIES_POLICY_MANAGE`, or `Permissions.POLICIES_POLICY_AUDIT` + +--- + +## Request + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `pageIndex` | number | No | 0 | The number of pages to skip before starting to collect the result set | +| `pageSize` | number | No | 20 | The number of items to return | +| `type` | string | No | — | Filter by policy type (e.g. `local`) | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +The `X-Total-Count` response header contains the total number of matching policies. + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "name": "iREC Policy", + "version": "1.0.0", + "description": "iREC renewable energy certificate policy", + "status": "PUBLISH", + "topicId": "0.0.4532001", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "userRoles": ["OWNER"] + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/policy-creation-using-the-guardian-apis/policy-preview-from-ipfs.md b/docs/policy-creation-using-the-guardian-apis/policy-preview-from-ipfs.md index 61c747cc48..defe66170d 100644 --- a/docs/policy-creation-using-the-guardian-apis/policy-preview-from-ipfs.md +++ b/docs/policy-creation-using-the-guardian-apis/policy-preview-from-ipfs.md @@ -1,51 +1,54 @@ # Policy Preview from IPFS -### POLICY PREVIEW FROM IPFS +**`POST /policies/import/message/preview`** -{% swagger method="post" path="" baseUrl="/policies/import/message/preview" summary="Policy preview from IPFS" %} -{% swagger-description %} -Previews the policy from IPFS without loading it into the local DB. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +Previews a policy from IPFS without importing it into the local database. -{% swagger-parameter in="body" type="Object" name="messageID" required="true" %} -Object that contains the identifier of the Hedera message which contains the IPFS CID of the policy -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/PreviewPolicy' -} -``` -{% endswagger-response %} +**Permission:** `Permissions.POLICIES_POLICY_CREATE` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- + +## Request + +### Request Body -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +```json { - // Response + "messageId": "1680000000.000000001" } ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `messageId` | string | Yes | The Hedera message ID containing the IPFS CID of the policy | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "policy": { + "name": "iREC Policy", + "version": "1.0.0", + "description": "iREC standard policy", + "messageId": "1680000000.000000001" + }, + "schemas": [] } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Message ID is missing or invalid | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/policy-creation-using-the-guardian-apis/policy-validation.md b/docs/policy-creation-using-the-guardian-apis/policy-validation.md index 87a1d68958..da3e522688 100644 --- a/docs/policy-creation-using-the-guardian-apis/policy-validation.md +++ b/docs/policy-creation-using-the-guardian-apis/policy-validation.md @@ -1,51 +1,55 @@ # Policy Validation -### VALIDATES POLICY +**`POST /policies/validate`** -{% swagger method="post" path="" baseUrl="/policies/validate" summary="Validates policy" %} -{% swagger-description %} -Validates selected policy. Only users with the Standard Registry role are allowed to make the request -{% endswagger-description %} +Validates the provided policy configuration and returns validation results without saving. -{% swagger-parameter in="body" type="application/jsonn" required="true" %} -Object that contains policy configuration -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/ValidatePolicy' -} -``` -{% endswagger-response %} +**Permission:** `Permissions.POLICIES_POLICY_UPDATE` or `Permissions.POLICIES_POLICY_REVIEW` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- + +## Request + +### Request Body -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +```json { - // Response + "name": "iREC Policy", + "version": "1.0.0", + "config": {} } ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +The request body is the full policy configuration object to validate. + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "results": { + "isValid": true, + "errors": [] + }, + "policy": { + "id": "63e3e5e8a01b3c001234abcd", + "name": "iREC Policy", + "version": "1.0.0" + } } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/policy-creation-using-the-guardian-apis/prerequesite-steps.md b/docs/policy-creation-using-the-guardian-apis/prerequesite-steps.md index ccbabaf765..aa86d50b86 100644 --- a/docs/policy-creation-using-the-guardian-apis/prerequesite-steps.md +++ b/docs/policy-creation-using-the-guardian-apis/prerequesite-steps.md @@ -1,300 +1,141 @@ -# Prerequesite Steps +# Prerequisite Steps -Prior to creating a policy there are a few steps that need to be done first. Please see below for the prerequesite steps: +Before calling any Policy API endpoint, complete the following setup steps. -### **New Standard Registry registration** +--- -{% swagger method="post" path="" baseUrl="/api/v1/accounts/register" summary="" %} -{% swagger-description %} +## 1. Register a Standard Registry Account -{% endswagger-description %} +**`POST /api/v1/accounts/register`** -{% swagger-parameter in="body" name="username" type="String" required="true" %} -njkqur8x -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="password" type="String" required="true" %} -test -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="role" type="String" required="true" %} -STANDARD_REGISTRY -{% endswagger-parameter %} - -{% swagger-response status="201: Created" description="Created" %} - - -```typescript +```json { - username: string - password: string - password_confirmation: string - role: string + "username": "example_user", + "password": "examplePassword123", + "role": "STANDARD_REGISTRY" } ``` -{% endswagger-response %} -{% endswagger %} - -### **Login** - -{% swagger method="post" path="" baseUrl="/api/v1/accounts/login" summary="" %} -{% swagger-description %} - -{% endswagger-description %} - -{% swagger-parameter in="body" name="username" type="String" required="true" %} -njkgur8x -{% endswagger-parameter %} -{% swagger-parameter in="body" name="password" type="String" required="true" %} -test -{% endswagger-parameter %} +**Response `201 Created`:** -{% swagger-response status="200: OK" description="Successful Operation" %} -````javascript -```typescript +```json { - username: string - did: any - role: string - accessToken: string + "username": "example_user", + "role": "STANDARD_REGISTRY" } ``` -```` -{% endswagger-response %} -{% endswagger %} -### **Hedera account creation** +--- -{% swagger method="get" path="" baseUrl="/api/v1/demo/random-key" summary="" %} -{% swagger-description %} +## 2. Obtain a Bearer Token -{% endswagger-description %} +**`POST /api/v1/accounts/login`** -{% swagger-response status="200: OK" description="" %} -```javascript +```json { - - "id":"0.0.29511776", - "key":"302e020100300506032b6570042204200c8d2abbdd9aee64eed6e4891c276aa50248ab182c0cd7dfbec8506e5eaaaef8" - + "username": "example_user", + "password": "examplePassword123" } ``` -{% endswagger-response %} -{% endswagger %} - -### **Address book creation** - -{% swagger method="put" path="" baseUrl="/api/v1/profile" summary="" %} -{% swagger-description %} - -{% endswagger-description %} - -{% swagger-parameter in="body" name="hederaAccountId" required="true" %} -0.0.29511776 -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="hederaAccountKey" required="true" %} -302e020100300506032b6570042204200c8d2abbdd9aee64eed6e4891c276aa50248ab182c0cd7dfbec8506e5eaaaef8 -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="name" type="String" required="true" %} -DD -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="type" type="String" required="true" %} -StandardRegistry -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="context" type="String" required="true" %} - - -[https://localhost/schema](https://localhost/schema) - - -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="aopnetname" type="String" required="true" %} -Test Identity SDK appnet -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="didSrverURL" required="true" type="URL" %} - - -[http://localhost:3000/api/v1](http://localhost:3000/api/v1) - - -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="didTopicMemo" required="true" %} -Test Identity SDK appnet DID topic -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="vcTopicMemo" required="true" %} -Test Identity SDK appnet DID topic -{% endswagger-parameter %} -{% endswagger %} - -### **iRec schema creation** - -{% swagger method="post" path="" baseUrl="/api/v1/schemas" summary="" %} -{% swagger-description %} - -{% endswagger-description %} - -{% swagger-parameter in="body" name="uuid" required="true" %} -d018a6ce-71f0-4bc5-9380-6bae4d4bb5bb -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="status" required="true" %} -DRAFT -{% endswagger-parameter %} -{% swagger-parameter in="body" name="readonly" required="true" %} -False -{% endswagger-parameter %} +**Response `200 OK`:** -{% swagger-parameter in="body" name="name" type="String" required="true" %} -iRec -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="description" type="String" required="true" %} -iRec Application Form -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="entity" type="String" required="true" %} -VC -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="owner" type="String" required="false" %} - -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="version" type="String" required="false" %} - -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="document" required="true" %} -{"$id":"#d018a6ce-71f0-4bc5-9380-6bae4d4bb5bb","$comment":"{ \\"term\\": \\"d018a6ce-71f0-4bc5-9380-6bae4d4bb5bb\\", \\"@id\\": \\"https://localhost/schema#d018a6ce-71f0-4bc5-9380-6bae4d4bb5bb\\" }","title":"iRec","description":"iRec application form","type":"object","properties":{"@context":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"readOnly":true},"type":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"readOnly":true},"id":{"type":"string","readOnly":true},"field0":{"title":"Test field","description":"Test field","readOnly":false,"$comment":"{ \\"term\\": \\"field0\\", \\"@id\\": \\"https://www.schema.org/text\\" }","type":"string"},"field1":{"title":"Required field","description":"Required field","readOnly":false,"$comment":"{ \\"term\\": \\"field1\\", \\"@id\\": \\"https://www.schema.org/text\\" }","type":"string"},"field2":{"title":"Multiple field","description":"Multiple field","readOnly":false,"type":"array","items":{"type":"string"},"$comment":"{ \\"term\\": \\"field2\\", \\"@id\\": \\"https://www.schema.org/text\\" }"},"policyId":{"title":"policyId","description":"policyId","readOnly":true,"$comment":"{ \\"term\\": \\"policyId\\", \\"@id\\": \\"https://www.schema.org/text\\" }","type":"string"}},"required":["@context","type","field1","policyId"],"additionalProperties":false} -{% endswagger-parameter %} - -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript +```json { - ... - { - "id":"61ee7ecd9c02660014fa662e", - ... - } + "username": "example_user", + "did": null, + "role": "STANDARD_REGISTRY", + "accessToken": "" } ``` -{% endswagger-response %} -{% endswagger %} - -### **iRec schema publish** - -{% swagger method="put" path="" baseUrl="/api/v1/schemas/61ee7ecd9c02660014fa662e/publish" summary="" %} -{% swagger-description %} - -{% endswagger-description %} - -{% swagger-parameter in="body" name="version" required="true" %} -{"version":"1.0.0"} -{% endswagger-parameter %} - -{% swagger-response status="200: OK" description="Ok" %} - -{% endswagger-response %} - -{% swagger-response status="403: Forbidden" description="Forbidden" %} - -{% endswagger-response %} - -{% swagger-response status="404: Not Found" description="Not Found" %} - -{% endswagger-response %} - -{% swagger-response status="422: Unprocessable Entity" description="Unprocessable Entity" %} +Use the `accessToken` value as the Bearer token in the `Authorization` header for all subsequent requests: ``` -Version already exists. +Authorization: Bearer ``` -``` -Schema is published. -``` -{% endswagger-response %} +--- -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} +## 3. Create a Hedera Account (Demo) -{% endswagger-response %} -{% endswagger %} +**`GET /api/v1/demo/random-key`** -### **Token creation** +```json +{ + "id": "0.0.4532001", + "key": "302e020100300506032b657004220420..." +} +``` -{% swagger method="post" path="" baseUrl="/api/v1/tokens" summary="" %} -{% swagger-description %} +--- -{% endswagger-description %} +## 4. Set Up the Standard Registry Profile -{% swagger-parameter in="body" name="tokenName" type="String" required="true" %} -iRec -{% endswagger-parameter %} +**`PUT /api/v1/profile`** -{% swagger-parameter in="body" name="tokenSymbol" type="String" required="true" %} -iRec -{% endswagger-parameter %} +```json +{ + "hederaAccountId": "0.0.4532001", + "hederaAccountKey": "302e020100300506032b657004220420...", + "name": "My Registry", + "type": "StandardRegistry" +} +``` -{% swagger-parameter in="body" name="tokenType" type="String" required="true" %} -fungible -{% endswagger-parameter %} +--- -{% swagger-parameter in="body" name="decimals" type="String" required="true" %} -2 -{% endswagger-parameter %} +## 5. Create and Publish a Schema -{% swagger-parameter in="body" name="initialsupply" type="String" required="true" %} -0 -{% endswagger-parameter %} +Create a schema via **`POST /api/v1/schemas`** with the schema document, then publish it via **`PUT /api/v1/schemas/{schemaId}/publish`** with body `{ "version": "1.0.0" }`. -{% swagger-parameter in="body" name="enableAdmin" type="Boolean" required="false" %} -true -{% endswagger-parameter %} +--- -{% swagger-parameter in="body" name="changeSupply" type="Boolean" required="false" %} -true -{% endswagger-parameter %} +## 6. Create a Token -{% swagger-parameter in="body" name="enableFreeze" type="Boolean" required="false" %} -true -{% endswagger-parameter %} +**`POST /api/v1/tokens`** -{% swagger-parameter in="body" name="enableKYC" type="Boolean" required="false" %} -true -{% endswagger-parameter %} +```json +{ + "tokenName": "Example Token", + "tokenSymbol": "EXT", + "tokenType": "fungible", + "decimals": "2", + "initialSupply": "0", + "enableAdmin": true, + "changeSupply": true, + "enableFreeze": true, + "enableKYC": true, + "enableWipe": true +} +``` -{% swagger-parameter in="body" name="enableWipe" type="Boolean" required="false" %} -true -{% endswagger-parameter %} +**Response `201 Created`:** -{% swagger-response status="201: Created" description="Created" %} -```javascript +```json { - - "id":"61ee817b9c02660014fa662f", - "tokenId":"0.0.29511821", - ... - + "id": "63e3e5e8a01b3c001234abcd", + "tokenId": "0.0.5000001" } ``` -{% endswagger-response %} -{% swagger-response status="422: Unprocessable Entity" description="Unprocessable Entity" %} +--- + +## Base URL +All policy endpoints are relative to: ``` -User not registered +/api/v1/policies ``` -{% endswagger-response %} -{% endswagger %} + +## Pagination + +Endpoints that return lists support standard pagination query parameters: + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `pageIndex` | number | 0 | Zero-based page index | +| `pageSize` | number | 20 | Number of items per page | + +The total item count is returned in the `X-Total-Count` response header. diff --git a/docs/policy-creation-using-the-guardian-apis/publish-a-policy.md b/docs/policy-creation-using-the-guardian-apis/publish-a-policy.md index 49091ff079..c56aa611cf 100644 --- a/docs/policy-creation-using-the-guardian-apis/publish-a-policy.md +++ b/docs/policy-creation-using-the-guardian-apis/publish-a-policy.md @@ -1,55 +1,55 @@ # Publish a Policy -### PUBLISH POLICY USING SPECIFIED POLICY ID +**`PUT /policies/{policyId}/publish`** -{% swagger method="put" path="" baseUrl="/policies/{policyId}/publish" summary="Publishes the policy onto IPFS" %} -{% swagger-description %} -Publishes the policy with the specified (internal) policy ID onto IPFS, sends a message featuring its IPFS CID into the corresponding Hedera topic. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +Publishes the policy with the specified ID onto IPFS and sends a message with its IPFS CID into the corresponding Hedera topic. -{% swagger-parameter in="path" name="policyID" type="String" required="true" %} -Selected policy ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-parameter in="body" type="Object" name="policyVersion" required="true" %} -Object that contains policy version -{% endswagger-parameter %} +**Permission:** `Permissions.POLICIES_POLICY_REVIEW` -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/PublishPolicy' -} -``` -{% endswagger-response %} +--- -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `policyId` | string | Yes | The policy ID (MongoDB ObjectId, e.g. `63e3e5e8a01b3c001234abcd`) | -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +### Request Body + +```json { - // Response + "policyVersion": "1.0.0" } ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `policyVersion` | string | Yes | The version string to assign when publishing (e.g. `1.0.0`) | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "valid": true, + "policies": [] } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Policy not found | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/policy-creation-using-the-guardian-apis/request-block-data.md b/docs/policy-creation-using-the-guardian-apis/request-block-data.md index 88ae65bbd7..49609c4a37 100644 --- a/docs/policy-creation-using-the-guardian-apis/request-block-data.md +++ b/docs/policy-creation-using-the-guardian-apis/request-block-data.md @@ -1,55 +1,47 @@ # Request Block Data -### REQUESTING BLOCK DATA +**`GET /policies/{policyId}/blocks/{uuid}`** -{% swagger method="get" path="" baseUrl="/policies/{policyId}/blocks/{uuid}" summary="Requests block data" %} -{% swagger-description %} -Requests block data. Only users with a role that described in block are allowed to make the request. -{% endswagger-description %} +Requests data for the specified block within a policy. Only users with a role permitted by the block are allowed to make this request. -{% swagger-parameter in="path" name="policyID" type="String" required="true" %} -Selected policy ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-parameter in="path" name="uuid" type="String" required="true" %} -Selected block UUID -{% endswagger-parameter %} +**Permission:** `Permissions.POLICIES_POLICY_EXECUTE` or `Permissions.POLICIES_POLICY_MANAGE` -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/PolicyBlockData' -} -``` -{% endswagger-response %} +--- -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `policyId` | string | Yes | The policy ID (MongoDB ObjectId, e.g. `63e3e5e8a01b3c001234abcd`) | +| `uuid` | string | Yes | The block UUID identifier | + +--- + +## Response -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "blockType": "requestVcDocumentBlock", + "schema": "#iREC_Application", + "data": {} } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Policy or block not found | +| `503 Service Unavailable` | Policy block is temporarily unavailable | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/policy-creation-using-the-guardian-apis/retrieval-of-data-from-root-policy-block.md b/docs/policy-creation-using-the-guardian-apis/retrieval-of-data-from-root-policy-block.md index e71de8ea01..cd09750439 100644 --- a/docs/policy-creation-using-the-guardian-apis/retrieval-of-data-from-root-policy-block.md +++ b/docs/policy-creation-using-the-guardian-apis/retrieval-of-data-from-root-policy-block.md @@ -1,51 +1,45 @@ # Retrieval of Data from Root Policy Block -### RETRIEVING DATA FROM ROOT POLICY BLOCK +**`GET /policies/{policyId}/blocks`** -{% swagger method="get" path="" baseUrl="/policies/{policyId}/blocks" summary="Retrieves data for the policy root block" %} -{% swagger-description %} -Returns data from the root policy block. Only users with the Standard Registry and Installer role are allowed to make the request -{% endswagger-description %} +Returns data from the root policy block for the specified policy. -{% swagger-parameter in="path" name="policyID" type="String" required="true" %} -Selected policy ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/PolicyBlock' -} -``` -{% endswagger-response %} +**Permission:** `Permissions.POLICIES_POLICY_EXECUTE` or `Permissions.POLICIES_POLICY_MANAGE` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `policyId` | string | Yes | The policy ID (MongoDB ObjectId, e.g. `63e3e5e8a01b3c001234abcd`) | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "blockType": "interfaceContainerBlock", + "children": [] } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Policy not found | +| `503 Service Unavailable` | Policy block is temporarily unavailable | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/policy-creation-using-the-guardian-apis/retrieves-block-data-by-tag.md b/docs/policy-creation-using-the-guardian-apis/retrieves-block-data-by-tag.md index 6d85b32a02..049f5da2e2 100644 --- a/docs/policy-creation-using-the-guardian-apis/retrieves-block-data-by-tag.md +++ b/docs/policy-creation-using-the-guardian-apis/retrieves-block-data-by-tag.md @@ -1,53 +1,47 @@ # Retrieves Block Data by Tag -### RETRIEVES BLOCK DATA BY TAG +**`GET /policies/{policyId}/tag/{tagName}/blocks`** -{% swagger method="get" path="" baseUrl="/policies/{policyId}/tag/{tag}/blocks" summary="Requests block data" %} -{% swagger-description %} -Requests block data by tag. Only users with a role that described in block are allowed to make the request. -{% endswagger-description %} +Requests block data for the block identified by tag name within the specified policy. -{% swagger-parameter in="path" name="policyId" type="String" required="true" %} -Selected Policy ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-parameter in="path" name="tag" type="String" required="true" %} -Tag from the selected policy -{% endswagger-parameter %} +**Permission:** `Permissions.POLICIES_POLICY_EXECUTE` or `Permissions.POLICIES_POLICY_MANAGE` -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - application/json: - schema: - $ref: '#/components/schemas/PolicyBlockData' -} -``` -{% endswagger-response %} +--- -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `policyId` | string | Yes | The policy ID (MongoDB ObjectId, e.g. `63e3e5e8a01b3c001234abcd`) | +| `tagName` | string | Yes | The block tag name (e.g. `submit_application`) | + +--- + +## Response -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +### Success Response + +**Status:** `200 OK` + +```json { - application/json: - schema: - $ref: '#/components/schemas/Error' + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "blockType": "requestVcDocumentBlock", + "schema": "#iREC_Application", + "data": {} } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Policy or block with given tag not found | +| `503 Service Unavailable` | Policy block is temporarily unavailable | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/policy-creation-using-the-guardian-apis/retrieves-policy-configuration.md b/docs/policy-creation-using-the-guardian-apis/retrieves-policy-configuration.md index 60e17fc7ac..e1b7153ba0 100644 --- a/docs/policy-creation-using-the-guardian-apis/retrieves-policy-configuration.md +++ b/docs/policy-creation-using-the-guardian-apis/retrieves-policy-configuration.md @@ -1,51 +1,50 @@ # Retrieves Policy Configuration -### **RETRIEVES POLICY CONFIGURATION** +**`GET /policies/{policyId}`** -{% swagger method="get" path="policies/{policyId}" baseUrl="/" summary="Retrieves policy configuration" %} -{% swagger-description %} -Retrieves policy configuration for the specified policy ID. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +Retrieves the full policy configuration object for the specified policy ID. -{% swagger-parameter in="query" name="policyID" type="String" required="true" %} -Selected policy ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/PolicyConfig' -} -``` -{% endswagger-response %} +**Permission:** `Permissions.POLICIES_POLICY_READ`, `Permissions.POLICIES_POLICY_EXECUTE`, `Permissions.POLICIES_POLICY_MANAGE`, or `Permissions.POLICIES_POLICY_AUDIT` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `policyId` | string | Yes | The policy ID (MongoDB ObjectId, e.g. `63e3e5e8a01b3c001234abcd`) | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "id": "63e3e5e8a01b3c001234abcd", + "name": "iREC Policy", + "version": "1.0.0", + "description": "iREC standard policy", + "status": "DRAFT", + "creator": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "topicId": "0.0.4532001", + "config": {} } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Policy not found | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/policy-creation-using-the-guardian-apis/returns-block-id-by-tag.md b/docs/policy-creation-using-the-guardian-apis/returns-block-id-by-tag.md index 4e3535a267..47a437149d 100644 --- a/docs/policy-creation-using-the-guardian-apis/returns-block-id-by-tag.md +++ b/docs/policy-creation-using-the-guardian-apis/returns-block-id-by-tag.md @@ -1,57 +1,46 @@ -# Returns Block ID by tag +# Returns Block ID by Tag -### RETURNING BLOCK ID FROM POLICY BY TAG +**`GET /policies/{policyId}/tag/{tagName}`** -{% swagger method="get" path="" baseUrl="/policies/{policyId}/tag/{tag}" summary="Requests block ID from a policy by tag" %} -{% swagger-description %} -Requests block ID from a policy by tag. Only users with the Standard Registry and Installer roles are allowed to make the request -{% endswagger-description %} +Returns the block configuration (including block ID) for the block matching the given tag name within the specified policy. -{% swagger-parameter in="path" name="policyID" type="String" required="true" %} -Selected policy ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-parameter in="path" name="tag" type="String" required="true" %} -Tag from the selected policy -{% endswagger-parameter %} +**Permission:** `Permissions.POLICIES_POLICY_EXECUTE` or `Permissions.POLICIES_POLICY_MANAGE` -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - application/json: - schema: - type: object - properties: - id: - type: string -} -``` -{% endswagger-response %} +--- -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `policyId` | string | Yes | The policy ID (MongoDB ObjectId, e.g. `63e3e5e8a01b3c001234abcd`) | +| `tagName` | string | Yes | The block tag name (e.g. `submit_application`) | + +--- + +## Response -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "blockType": "requestVcDocumentBlock", + "tag": "submit_application" } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Policy or block with given tag not found | +| `422 Unprocessable Entity` | Tag lookup error | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/policy-creation-using-the-guardian-apis/returns-list-of-groups-of-a-particular-user.md b/docs/policy-creation-using-the-guardian-apis/returns-list-of-groups-of-a-particular-user.md index f583ada13e..25d7f8b1d3 100644 --- a/docs/policy-creation-using-the-guardian-apis/returns-list-of-groups-of-a-particular-user.md +++ b/docs/policy-creation-using-the-guardian-apis/returns-list-of-groups-of-a-particular-user.md @@ -1,64 +1,49 @@ -# Returns list of Groups of a particular user +# Returns List of Groups of a Particular User -{% swagger method="get" path="" baseUrl="/policies/{policyId}/groups" summary="Returns a list of groups the user is a member of." %} -{% swagger-description %} -Returns a list of groups the user is a member of. -{% endswagger-description %} +**`GET /policies/{policyId}/groups`** -{% swagger-parameter in="path" name="policyId" type="String" required="true" %} -Selected policy ID. -{% endswagger-parameter %} +Returns a list of policy groups that the current user is a member of. -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - type: array - items: - type: object - properties: - id: - type: string - uuid: - type: string - role: - type: string - groupLabel: - type: string - groupName: - type: string - active: - type: boolean -} -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +**Permission:** `Permissions.POLICIES_POLICY_EXECUTE` or `Permissions.POLICIES_POLICY_MANAGE` -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `policyId` | string | Yes | The policy ID (MongoDB ObjectId, e.g. `63e3e5e8a01b3c001234abcd`) | -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "role": "INSTALLER", + "groupLabel": "Installers", + "groupName": "Installer Group", + "active": true + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Policy not found | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/policy-creation-using-the-guardian-apis/sends-data-to-specified-block-by-tag.md b/docs/policy-creation-using-the-guardian-apis/sends-data-to-specified-block-by-tag.md index afb706ff7b..dc41a77cf0 100644 --- a/docs/policy-creation-using-the-guardian-apis/sends-data-to-specified-block-by-tag.md +++ b/docs/policy-creation-using-the-guardian-apis/sends-data-to-specified-block-by-tag.md @@ -1,50 +1,57 @@ -# Sends Data to specified Block by Tag +# Sends Data to Specified Block by Tag -{% swagger method="post" path="" baseUrl="/policies/{policyId}/tag/{tag}/blocks" summary="Sends data to the specified block." %} -{% swagger-description %} -Sends data to the specified block -{% endswagger-description %} +**`POST /policies/{policyId}/tag/{tagName}/blocks`** -{% swagger-parameter in="path" name="policyId" type="String" required="true" %} -Policy ID -{% endswagger-parameter %} +Sends data to the block identified by tag name within the specified policy. -{% swagger-parameter in="path" name="tag" type="String" required="true" %} -Tag from the selected policy -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +**Permission:** `Permissions.POLICIES_POLICY_EXECUTE` or `Permissions.POLICIES_POLICY_MANAGE` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `policyId` | string | Yes | The policy ID (MongoDB ObjectId, e.g. `63e3e5e8a01b3c001234abcd`) | +| `tagName` | string | Yes | The block tag name (e.g. `submit_application`) | -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +### Request Body + +```json { - // Response + "document": {}, + "ref": null } ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +The request body is a JSON object containing the data to submit to the block (exact schema depends on the block type). + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "blockType": "requestVcDocumentBlock", + "data": {} } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Policy or block with given tag not found | +| `422 Unprocessable Entity` | Invalid or rejected block data | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/policy-creation-using-the-guardian-apis/sends-data-to-specified-block.md b/docs/policy-creation-using-the-guardian-apis/sends-data-to-specified-block.md index 552c63c540..7f8409e3d6 100644 --- a/docs/policy-creation-using-the-guardian-apis/sends-data-to-specified-block.md +++ b/docs/policy-creation-using-the-guardian-apis/sends-data-to-specified-block.md @@ -1,52 +1,65 @@ # Sends Data to Specified Block -### SENDING BLOCK DATA +**`POST /policies/{policyId}/blocks/{uuid}`** -{% swagger method="post" path="" baseUrl="/policies/{policyId}/blocks/{uuid}" summary="Sends data to the specified block" %} -{% swagger-description %} -Sends data to the specified block -{% endswagger-description %} +Sends data to the specified block within a policy. -{% swagger-parameter in="path" name="policyID" type="String" required="true" %} -Selected policy ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-parameter in="path" name="uuid" type="String" required="true" %} -Selected block UUID -{% endswagger-parameter %} +**Permission:** `Permissions.POLICIES_POLICY_EXECUTE` or `Permissions.POLICIES_POLICY_MANAGE` -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `policyId` | string | Yes | The policy ID (MongoDB ObjectId, e.g. `63e3e5e8a01b3c001234abcd`) | +| `uuid` | string | Yes | The block UUID identifier | + +### Query Parameters -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `timeout` | number | No | 60000 | Request timeout in milliseconds | +| `waitRemotePolicy` | boolean | No | true | Wait for a response from a remote policy | + +### Request Body + +```json { - // Response + "document": {}, + "ref": null } ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +The request body is a JSON object containing the data to submit to the block (exact schema depends on the block type). + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "blockType": "requestVcDocumentBlock", + "data": {} } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Policy or block not found | +| `422 Unprocessable Entity` | Invalid or rejected block data | +| `503 Service Unavailable` | Policy block is temporarily unavailable | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/policy-creation-using-the-guardian-apis/updates-policy-configuration.md b/docs/policy-creation-using-the-guardian-apis/updates-policy-configuration.md index 5d87e40f58..ce369968e6 100644 --- a/docs/policy-creation-using-the-guardian-apis/updates-policy-configuration.md +++ b/docs/policy-creation-using-the-guardian-apis/updates-policy-configuration.md @@ -1,55 +1,64 @@ # Updates Policy Configuration -### UPDATES **POLICY CONFIGURATION** +**`PUT /policies/{policyId}`** -{% swagger method="put" path="" baseUrl="/policies/{policyId}" summary="Updates policy configuration" %} -{% swagger-description %} -Updates policy configuration for the specified policy ID. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +Updates the policy configuration for the specified policy ID. -{% swagger-parameter in="path" name="policyID" type="String" required="true" %} -Selected policy ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-parameter in="body" type="application/json" required="true" %} -Object that contains policy configuration -{% endswagger-parameter %} +**Permission:** `Permissions.POLICIES_POLICY_UPDATE` -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/PolicyConfig' -} -``` -{% endswagger-response %} +--- -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `policyId` | string | Yes | The policy ID (MongoDB ObjectId, e.g. `63e3e5e8a01b3c001234abcd`) | -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +### Request Body + +```json { - // Response + "name": "iREC Policy", + "version": "1.0.0", + "description": "Updated description", + "config": {} } ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | No | Policy name | +| `version` | string | No | Policy version string | +| `description` | string | No | Human-readable description | +| `config` | object | No | Policy block configuration tree | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "id": "63e3e5e8a01b3c001234abcd", + "name": "iREC Policy", + "version": "1.0.0", + "status": "DRAFT", + "config": {} } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Policy not found | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/policy-related-apis-for-asynchronous-execution/README.md b/docs/policy-related-apis-for-asynchronous-execution/README.md new file mode 100644 index 0000000000..cc9fe38066 --- /dev/null +++ b/docs/policy-related-apis-for-asynchronous-execution/README.md @@ -0,0 +1,29 @@ +# Policy APIs — Asynchronous Execution + +**Base URL:** `/api/v1/policies` + +Provides asynchronous endpoints for creating, publishing, and importing policies. All async endpoints return `{ taskId, expectation }` with status 202 Accepted. Poll `GET /tasks/{taskId}` for the result. + +**Authentication:** All endpoints require a valid JWT Bearer token (`Authorization: Bearer `). Obtain a token via `POST /accounts/login`. + +--- + +## Endpoints + +| Method | Endpoint | Description | Auth Required | +|--------|----------|-------------|---------------| +| POST | `/policies/push` | Creates a new policy (async). Poll `GET /tasks/{taskId}` for result. | Yes | +| PUT | `/policies/push/{policyId}/publish` | Publishes a policy (async). Poll `GET /tasks/{taskId}` for result. | Yes | +| POST | `/policies/push/import/file` | Imports a policy from a zip file (async). Poll `GET /tasks/{taskId}` for result. | Yes | +| POST | `/policies/push/import/message` | Imports a policy from IPFS via Hedera message ID (async). Poll `GET /tasks/{taskId}` for result. | Yes | +| POST | `/policies/push/import/message/preview` | Previews a policy from IPFS (async) | Yes | + +--- + +## Endpoint Details + +* [Creates New Policy](creates-new-policy.md) — `POST /policies/push` +* [Publishing a Policy](publishing-a-policy.md) — `PUT /policies/push/{policyId}/publish` +* [Importing a Policy from File](importing-a-policy-from-file.md) — `POST /policies/push/import/file` +* [Importing a Policy from IPFS](importing-a-policy-from-ipfs.md) — `POST /policies/push/import/message` +* [Policy Review](policy-review.md) — `POST /policies/push/import/message/preview` diff --git a/docs/policy-related-apis-for-asynchronous-execution/creates-new-policy.md b/docs/policy-related-apis-for-asynchronous-execution/creates-new-policy.md index fa1fb3d0cf..21a39a959b 100644 --- a/docs/policy-related-apis-for-asynchronous-execution/creates-new-policy.md +++ b/docs/policy-related-apis-for-asynchronous-execution/creates-new-policy.md @@ -1,49 +1,51 @@ -# Creates new Policy +# Creates New Policy (Async) -{% swagger method="post" path="" baseUrl=" /policies/push" summary="Creates a new policy" %} -{% swagger-description %} -Creates a new policy. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /policies/push`** -{% swagger-parameter in="body" required="true" %} -Object that contains policy configuration -{% endswagger-parameter %} +Creates a new policy asynchronously. Returns a task ID immediately; poll `GET /tasks/{taskId}` for the result. -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Task' -} -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +**Permission:** `Permissions.POLICIES_POLICY_CREATE` + +--- + +## Request + +### Request Body -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +```json { - // Response + "name": "iREC Policy", + "version": "1.0.0", + "description": "iREC standard policy", + "config": {} } ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +The request body is the full policy configuration object. + +--- + +## Response + +### Success Response + +**Status:** `202 Accepted` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Create policy" } ``` -{% endswagger-response %} -{% endswagger %} + +Poll `GET /tasks/{taskId}` to retrieve the result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/policy-related-apis-for-asynchronous-execution/importing-a-policy-from-file.md b/docs/policy-related-apis-for-asynchronous-execution/importing-a-policy-from-file.md index 07c18ab322..2956b074fb 100644 --- a/docs/policy-related-apis-for-asynchronous-execution/importing-a-policy-from-file.md +++ b/docs/policy-related-apis-for-asynchronous-execution/importing-a-policy-from-file.md @@ -1,49 +1,51 @@ -# Importing a Policy from file +# Importing a Policy from File (Async) -{% swagger method="post" path="" baseUrl="/policies/push/import/file" summary="Imports new policy and all associated artifacts, such as schemas and VCs, from the provided zip file into the local DB." %} -{% swagger-description %} -Imports new policy and all associated artifacts, such as schemas and VCs, from the provided zip file into the local DB. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /policies/push/import/file`** -{% swagger-parameter in="body" required="true" type="String" %} -A zip file that contains the policy and associated schemas and VCs to be imported. -{% endswagger-parameter %} +Imports a new policy and all associated artifacts from a zip file asynchronously. Returns a task ID immediately; poll `GET /tasks/{taskId}` for the result. -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Task' -} -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +**Permission:** `Permissions.POLICIES_POLICY_CREATE` -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- + +## Request + +### Query Parameters -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `versionOfTopicId` | string | No | — | The topic ID of the policy version to associate | +| `demo` | boolean | No | false | Import the policy in demo mode | + +### Request Body + +The request body must be the raw binary content of a `.zip` file exported from Guardian. + +**Content-Type:** `application/octet-stream` + +--- + +## Response + +### Success Response + +**Status:** `202 Accepted` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Import policy file" } ``` -{% endswagger-response %} -{% endswagger %} + +Poll `GET /tasks/{taskId}` to retrieve the result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/policy-related-apis-for-asynchronous-execution/importing-a-policy-from-ipfs.md b/docs/policy-related-apis-for-asynchronous-execution/importing-a-policy-from-ipfs.md index 8533f52500..48249b0fa2 100644 --- a/docs/policy-related-apis-for-asynchronous-execution/importing-a-policy-from-ipfs.md +++ b/docs/policy-related-apis-for-asynchronous-execution/importing-a-policy-from-ipfs.md @@ -1,49 +1,58 @@ -# Importing a Policy from IPFS +# Importing a Policy from IPFS (Async) -{% swagger method="post" path="" baseUrl=" /policies/push/import/message" summary="Imports new policy and all associated artifacts from IPFS into the local DB." %} -{% swagger-description %} -Imports new policy and all associated artifacts from IPFS into the local DB. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /policies/push/import/message`** -{% swagger-parameter in="body" name="messageID" type="String" required="true" %} -Object that contains the identifier of the Hedera message which contains the IPFS CID of the Policy. -{% endswagger-parameter %} +Imports a new policy and all associated artifacts from IPFS asynchronously using the Hedera message ID. Returns a task ID immediately; poll `GET /tasks/{taskId}` for the result. -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Task' -} -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +**Permission:** `Permissions.POLICIES_POLICY_CREATE` + +--- + +## Request + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `versionOfTopicId` | string | No | — | The topic ID of the policy version to associate | +| `demo` | boolean | No | false | Import the policy in demo mode | -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +### Request Body + +```json { - // Response + "messageId": "1680000000.000000001" } ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `messageId` | string | Yes | The Hedera message ID containing the IPFS CID of the policy | + +--- + +## Response + +### Success Response + +**Status:** `202 Accepted` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Import policy message" } ``` -{% endswagger-response %} -{% endswagger %} + +Poll `GET /tasks/{taskId}` to retrieve the result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Message ID is missing | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/policy-related-apis-for-asynchronous-execution/policy-review.md b/docs/policy-related-apis-for-asynchronous-execution/policy-review.md index a026b0ff01..64179ab3db 100644 --- a/docs/policy-related-apis-for-asynchronous-execution/policy-review.md +++ b/docs/policy-related-apis-for-asynchronous-execution/policy-review.md @@ -1,49 +1,51 @@ -# Policy Review +# Policy Review — Preview from IPFS (Async) -{% swagger method="post" path="" baseUrl="/policies/push/import/message/preview" summary="Previews the policy from IPFS without loading it into the local DB." %} -{% swagger-description %} -Previews the policy from IPFS without loading it into the local DB. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /policies/push/import/message/preview`** -{% swagger-parameter in="body" name="messageId" type="String" required="true" %} -Object that contains the identifier of the Hedera message which contains the IPFS CID of the policy. -{% endswagger-parameter %} +Previews a policy from IPFS asynchronously without importing it into the local database. Returns a task ID immediately; poll `GET /tasks/{taskId}` for the result. -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Task' -} -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +**Permission:** `Permissions.POLICIES_POLICY_CREATE` + +--- + +## Request + +### Request Body -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +```json { - // Response + "messageId": "1680000000.000000001" } ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `messageId` | string | Yes | The Hedera message ID containing the IPFS CID of the policy | + +--- + +## Response + +### Success Response + +**Status:** `202 Accepted` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Preview policy message" } ``` -{% endswagger-response %} -{% endswagger %} + +Poll `GET /tasks/{taskId}` to retrieve the preview result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Message ID is missing | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/policy-related-apis-for-asynchronous-execution/publishing-a-policy.md b/docs/policy-related-apis-for-asynchronous-execution/publishing-a-policy.md index 4eab4902ef..b83fb600a0 100644 --- a/docs/policy-related-apis-for-asynchronous-execution/publishing-a-policy.md +++ b/docs/policy-related-apis-for-asynchronous-execution/publishing-a-policy.md @@ -1,53 +1,57 @@ -# Publishing a Policy +# Publishing a Policy (Async) -{% swagger method="put" path="" baseUrl="/policies/push/{policyId}/publish" summary="Publishes the policy with the specified (internal) policy ID onto IPFS, sends a message featuring its IPFS CID into the corresponding Hedera topic." %} -{% swagger-description %} -Publishes the policy with the specified (internal) policy ID onto IPFS, sends a message featuring its IPFS CID into the corresponding Hedera topic. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`PUT /policies/push/{policyId}/publish`** -{% swagger-parameter in="path" name="policyID" type="String" required="true" %} -policy ID -{% endswagger-parameter %} +Publishes the specified policy onto IPFS asynchronously, sending a message with its IPFS CID to the corresponding Hedera topic. Returns a task ID immediately; poll `GET /tasks/{taskId}` for the result. -{% swagger-parameter in="body" %} -Object that contains policy version. -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Task' -} -``` -{% endswagger-response %} +**Permission:** `Permissions.POLICIES_POLICY_REVIEW` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `policyId` | string | Yes | The policy ID (MongoDB ObjectId, e.g. `63e3e5e8a01b3c001234abcd`) | -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +### Request Body + +```json { - // Response + "policyVersion": "1.0.0" } ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `policyVersion` | string | Yes | The version string to assign when publishing (e.g. `1.0.0`) | + +--- + +## Response + +### Success Response + +**Status:** `202 Accepted` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Publish policy" } ``` -{% endswagger-response %} -{% endswagger %} + +Poll `GET /tasks/{taskId}` to retrieve the result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Policy not found | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/policy-repository-apis/README.md b/docs/policy-repository-apis/README.md new file mode 100644 index 0000000000..8aa28cfa9a --- /dev/null +++ b/docs/policy-repository-apis/README.md @@ -0,0 +1,149 @@ +# Policy Repository APIs + +Base URL: `/api/v1/policy-labels` + +These endpoints provide read access to user lists, schema lists, and document lists within a specific policy instance. Primarily used by administrators and external tools inspecting policy state. + +--- + +## GET /policy-labels/:policyId/users + +Returns the list of usernames that have participated in (or registered with) the specified policy. + +**Authentication:** Required (Bearer JWT) +**Permission:** `POLICIES_POLICY_READ` + +### Path Parameters + +| Parameter | Type | Required | Description | +|---|---|---|---| +| policyId | string | Yes | Policy MongoDB ObjectId (24 hex chars) | + +### Responses + +| Code | Description | +|---|---| +| 200 | Array of usernames | +| 401 | Unauthorized | +| 403 | Forbidden | +| 404 | Policy not found | +| 500 | Internal server error | + +### Example + +**Request:** +```http +GET /api/v1/policy-labels/63e3e5e8a01b3c001234abcd/users +Authorization: Bearer eyJhbGciOiJSUzI1NiJ9... +``` + +**Response 200:** +```json +["alice", "bob", "installer_1", "installer_2"] +``` + +--- + +## GET /policy-labels/:policyId/schemas + +Returns the list of schemas used within the specified policy. + +**Authentication:** Required (Bearer JWT) +**Permission:** `POLICIES_POLICY_READ` + +### Path Parameters + +| Parameter | Type | Required | Description | +|---|---|---|---| +| policyId | string | Yes | Policy MongoDB ObjectId | + +### Responses + +| Code | Description | +|---|---| +| 200 | Array of schema summary objects | +| 401 | Unauthorized | +| 403 | Forbidden | +| 404 | Policy not found | +| 500 | Internal server error | + +### Example + +**Request:** +```http +GET /api/v1/policy-labels/63e3e5e8a01b3c001234abcd/schemas +Authorization: Bearer eyJhbGciOiJSUzI1NiJ9... +``` + +**Response 200:** +```json +[ + { + "id": "63f1a2b3c4d5e6f789012345", + "name": "MRV Schema", + "entity": "MRV", + "version": "1.0.0", + "iri": "did:hedera:testnet:zSchemaIRI...", + "topicId": "0.0.4532002" + } +] +``` + +--- + +## GET /policy-labels/:policyId/documents + +Returns the list of VC documents submitted within the specified policy. + +**Authentication:** Required (Bearer JWT) +**Permission:** `POLICIES_POLICY_READ` + +### Path Parameters + +| Parameter | Type | Required | Description | +|---|---|---|---| +| policyId | string | Yes | Policy MongoDB ObjectId | + +### Query Parameters + +| Parameter | Type | Required | Description | +|---|---|---|---| +| pageIndex | number | No | Zero-based page number | +| pageSize | number | No | Items per page | +| type | string | No | Filter by document type (e.g. `VC`, `VP`) | +| owner | string | No | Filter by owner DID | + +### Responses + +| Code | Description | +|---|---| +| 200 | Array of document summaries. Total count in `X-Total-Count` header | +| 401 | Unauthorized | +| 403 | Forbidden | +| 404 | Policy not found | +| 500 | Internal server error | + +### Example + +**Request:** +```http +GET /api/v1/policy-labels/63e3e5e8a01b3c001234abcd/documents?pageIndex=0&pageSize=20&type=VC +Authorization: Bearer eyJhbGciOiJSUzI1NiJ9... +``` + +**Response 200:** +``` +X-Total-Count: 87 +``` +```json +[ + { + "id": "63e3e5e8a01b3c00aabbccdd", + "type": "VC", + "schema": "MRVDocument", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "status": "APPROVED", + "createDate": "2026-03-30T08:00:00.000Z" + } +] +``` diff --git a/docs/profile-apis/README.md b/docs/profile-apis/README.md new file mode 100644 index 0000000000..4677f57dc4 --- /dev/null +++ b/docs/profile-apis/README.md @@ -0,0 +1,41 @@ +# Profile APIs + +The Profile APIs allow users to manage their Hedera account credentials, DID documents, and policy keys. + +**Base URL:** `/api/v1/profiles` + +**Authentication:** All endpoints require a valid JWT Bearer token (`Authorization: Bearer `). Obtain a token via `POST /accounts/login`. + +--- + +## Endpoints + +| Method | Endpoint | Description | Auth Required | +|--------|----------|-------------|---------------| +| **`GET`** | `/profiles/{username}/` | Returns user account info | Yes | +| **`PUT`** | `/profiles/{username}` | Sets Hedera credentials for a user (synchronous) | Yes | +| **`PUT`** | `/profiles/push/{username}` | Sets Hedera credentials for a user (asynchronous) | Yes | +| **`GET`** | `/profiles/{username}/balance` | Returns the Hedera account balance for the specified user | Yes | +| **`PUT`** | `/profiles/restore/{username}` | Restores user data (policy, DID/VC documents) from Hedera topics | Yes | +| **`PUT`** | `/profiles/restore/topics/{username}` | Returns list of available recovery topics for a user's Hedera account | Yes | +| **`POST`** | `/profiles/did-document/validate` | Validates the format and structure of a DID document | Yes | +| **`POST`** | `/profiles/did-keys/validate` | Validates the keys within a DID document | Yes | +| **`GET`** | `/profiles/keys` | Returns a paginated list of existing policy signing keys | Yes | +| **`POST`** | `/profiles/keys` | Creates a new policy signing key | Yes | +| **`DELETE`** | `/profiles/keys/{id}` | Deletes a signing key by ID | Yes | + +--- + +## Endpoint Details + +* [User Account Information](user-account-information.md) — **`GET`** `/profiles/{username}/` +* [Setting User Credentials](setting-user-credentials.md) — **`PUT`** `/profiles/{username}` +* [Setting User Credentials Asynchronously](setting-user-credentials-asynchronously.md) — **`PUT`** `/profiles/push/{username}` +* [User Account Balance](user-account-balance.md) — **`GET`** `/profiles/{username}/balance` +* [Restoring User Profile](restoring-user-profile.md) — **`PUT`** `/profiles/restore/{username}` +* [List Recovery Topics](list-recovery-topics.md) — **`PUT`** `/profiles/restore/topics/{username}` +* [Validate DID Document](validate-did-document.md) — **`POST`** `/profiles/did-document/validate` +* [Validate DID Keys](validate-did-keys.md) — **`POST`** `/profiles/did-keys/validate` +* [Returns List of Keys](returns-list-of-keys.md) — **`GET`** `/profiles/keys` +* [Creates a Key](creates-a-key.md) — **`POST`** `/profiles/keys` +* [Deletes a Key](deletes-a-key.md) — **`DELETE`** `/profiles/keys/{id}` diff --git a/docs/profile-apis/creates-a-key.md b/docs/profile-apis/creates-a-key.md new file mode 100644 index 0000000000..0f22b26436 --- /dev/null +++ b/docs/profile-apis/creates-a-key.md @@ -0,0 +1,54 @@ +# Creates a Key + +**`POST /profiles/keys`** + +Creates a new policy signing key for the authenticated user. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.PROFILES_USER_UPDATE` + +--- + +## Request + +### Request Body + +```json +{ + "messageId": "1234567890.123456789", + "key": "ed25519" +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `messageId` | string | Yes | Hedera message ID to associate with this key | +| `key` | string | No | Key type (e.g. `ed25519`) | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "messageId": "1234567890.123456789", + "key": "ed25519", + "policyId": "63e3e5e8a01b3c001234abce", + "policyName": "Example Policy" +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Body or `messageId` is empty | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/profile-apis/deletes-a-key.md b/docs/profile-apis/deletes-a-key.md new file mode 100644 index 0000000000..25fa0561b6 --- /dev/null +++ b/docs/profile-apis/deletes-a-key.md @@ -0,0 +1,40 @@ +# Deletes a Key + +**`DELETE /profiles/keys/{id}`** + +Deletes a policy signing key by its ID. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.PROFILES_USER_UPDATE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `id` | string | Yes | The key identifier (MongoDB ObjectId) | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +true +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Invalid or missing `id` | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/profile-apis/list-recovery-topics.md b/docs/profile-apis/list-recovery-topics.md new file mode 100644 index 0000000000..8bb6de1146 --- /dev/null +++ b/docs/profile-apis/list-recovery-topics.md @@ -0,0 +1,58 @@ +# List Recovery Topics + +**`PUT /profiles/restore/topics/{username}`** + +Returns a list of available Hedera topics that can be used to restore the user's profile data asynchronously. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.PROFILES_RESTORE_ALL` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `username` | string | Yes | The username of the user | + +### Request Body + +```json +{ + "hederaAccountId": "0.0.4532001", + "hederaAccountKey": "302e020100300506032b657004220420..." +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `hederaAccountId` | string | Yes | The Hedera account ID | +| `hederaAccountKey` | string | Yes | The Hedera account private key | + +--- + +## Response + +### Success Response + +**Status:** `202 Accepted` + +```json +{ + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Get user topics" +} +``` + +Poll `GET /tasks/{taskId}` to retrieve the list of available recovery topics. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/profile-apis/restoring-user-profile.md b/docs/profile-apis/restoring-user-profile.md new file mode 100644 index 0000000000..2c15e16b00 --- /dev/null +++ b/docs/profile-apis/restoring-user-profile.md @@ -0,0 +1,58 @@ +# Restoring User Profile + +**`PUT /profiles/restore/{username}`** + +Restores user data (policy, DID documents, VC documents) from Hedera topics asynchronously. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.PROFILES_RESTORE_ALL` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `username` | string | Yes | The username of the user to restore | + +### Request Body + +```json +{ + "hederaAccountId": "0.0.4532001", + "hederaAccountKey": "302e020100300506032b657004220420..." +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `hederaAccountId` | string | Yes | The Hedera account ID | +| `hederaAccountKey` | string | Yes | The Hedera account private key | + +--- + +## Response + +### Success Response + +**Status:** `202 Accepted` + +```json +{ + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Restore user profile" +} +``` + +Poll `GET /tasks/{taskId}` to retrieve the result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/profile-apis/returns-list-of-keys.md b/docs/profile-apis/returns-list-of-keys.md new file mode 100644 index 0000000000..9241da85f6 --- /dev/null +++ b/docs/profile-apis/returns-list-of-keys.md @@ -0,0 +1,58 @@ +# Returns List of Keys + +**`GET /profiles/keys`** + +Returns a paginated list of existing policy signing keys for the authenticated user. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.PROFILES_USER_UPDATE` + +--- + +## Request + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `pageIndex` | number | No | 0 | Zero-based page index | +| `pageSize` | number | No | 20 | Items per page | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +The response includes an `X-Total-Count` header with the total number of keys. + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "messageId": "1234567890.123456789", + "key": "ed25519", + "policyId": "63e3e5e8a01b3c001234abce", + "policyName": "Example Policy" + } +] +``` + +| Field | Type | Description | +|-------|------|-------------| +| `id` | string | Key identifier | +| `messageId` | string | Hedera message ID associated with this key | +| `key` | string | Key type | +| `policyId` | string | Associated policy ID | +| `policyName` | string | Associated policy name | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/profile-apis/setting-user-credentials-asynchronously.md b/docs/profile-apis/setting-user-credentials-asynchronously.md index 3e07cfba24..6fda494aef 100644 --- a/docs/profile-apis/setting-user-credentials-asynchronously.md +++ b/docs/profile-apis/setting-user-credentials-asynchronously.md @@ -1,53 +1,63 @@ # Setting User Credentials Asynchronously -{% swagger method="put" path="" baseUrl="/profiles/push/{username}" summary="Sets Hedera credentials for the user" %} -{% swagger-description %} -Sets Hedera credentials for the user -{% endswagger-description %} +**`PUT /api/v1/profiles/push/{username}`** -{% swagger-parameter in="path" name="username" type="String" required="true" %} -The name of the user for whom to update the information. -{% endswagger-parameter %} +Sets Hedera credentials for the specified user asynchronously and returns a task identifier for polling the result. -{% swagger-parameter in="body" type="String" required="true" %} -Object that contains the Hedera account data. -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Task' -} -``` -{% endswagger-response %} +**Permission:** `Permissions.PROFILES_USER_UPDATE` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|------------|--------|----------|---------------------------------------------------| +| `username` | string | Yes | The name of the user for whom to update the information | -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +### Request Body + +```json { - // Response + "hederaAccountId": "0.0.4532001", + "hederaAccountKey": "302e...", + "useFireblocksSigning": false, + "fireblocksConfig": {} } ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +| Field | Type | Required | Description | +|----------------------|---------|----------|----------------------------------------------------| +| `hederaAccountId` | string | Yes | The Hedera account ID to associate with this user | +| `hederaAccountKey` | string | Yes | The private key for the Hedera account | +| `useFireblocksSigning` | boolean | No | Whether to use Fireblocks for transaction signing | +| `fireblocksConfig` | object | No | Fireblocks configuration details | + +--- + +## Response + +### Success Response + +**Status:** `202 Accepted` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Set credentials" } ``` -{% endswagger-response %} -{% endswagger %} + +Poll `GET /tasks/{taskId}` to retrieve the result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `400 Bad Request` | Malformed request body | +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/profile-apis/setting-user-credentials.md b/docs/profile-apis/setting-user-credentials.md index 4577db5336..5156fde29d 100644 --- a/docs/profile-apis/setting-user-credentials.md +++ b/docs/profile-apis/setting-user-credentials.md @@ -1,48 +1,54 @@ # Setting User Credentials -### SETS HEDERA CREDENTIALS +**`PUT /api/v1/profiles/{username}`** -{% swagger method="put" path="" baseUrl="/profiles/{username}" summary="Sets Hedera credentials for the user" %} -{% swagger-description %} -Sets Hedera credentials for the user. For users with the Standard Registry role it also creates an address book -{% endswagger-description %} +Sets Hedera credentials for the specified user. For users with the Standard Registry role it also creates an address book. -{% swagger-parameter in="path" name="username" type="String" required="true" %} -The name of the user for whom to update the information -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="201: Created" description="Successful Operation" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +**Permission:** `Permissions.PROFILES_USER_UPDATE` -{% swagger-response status="401: Unauthorized" description="" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request + +### Path Parameters -{% swagger-response status="500: Internal Server Error" description="" %} -```javascript +| Parameter | Type | Required | Description | +|------------|--------|----------|---------------------------------------------------| +| `username` | string | Yes | The name of the user for whom to update the information | + +### Request Body + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "hederaAccountId": "0.0.4532001", + "hederaAccountKey": "302e...", + "useFireblocksSigning": false, + "fireblocksConfig": {} } ``` -{% endswagger-response %} -{% endswagger %} + +| Field | Type | Required | Description | +|----------------------|---------|----------|----------------------------------------------------| +| `hederaAccountId` | string | Yes | The Hedera account ID to associate with this user | +| `hederaAccountKey` | string | Yes | The private key for the Hedera account | +| `useFireblocksSigning` | boolean | No | Whether to use Fireblocks for transaction signing | +| `fireblocksConfig` | object | No | Fireblocks configuration details | + +--- + +## Response + +### Success Response + +**Status:** `204 No Content` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `400 Bad Request` | Malformed request body | +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/profile-apis/user-account-balance.md b/docs/profile-apis/user-account-balance.md index f4ae751133..e62e7223b4 100644 --- a/docs/profile-apis/user-account-balance.md +++ b/docs/profile-apis/user-account-balance.md @@ -1,51 +1,41 @@ # User Account Balance -### RETURNS USER'S ACCOUNT BALANCE - -{% swagger method="get" path="" baseUrl="/profiles/{username}/balance" summary="Returns user's Hedera account balance" %} -{% swagger-description %} -Requests Hedera account balance. Only users with the Installer role are allowed to make the request -{% endswagger-description %} - -{% swagger-parameter in="path" name="username" type="String" required="true" %} -The name of the user for whom to fetch the balance -{% endswagger-parameter %} - -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - type: string -} -``` -{% endswagger-response %} +**`GET /api/v1/profiles/{username}/balance`** -{% swagger-response status="401: Unauthorized" description="" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +Returns the Hedera account balance for the specified user. -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} - -{% swagger-response status="500: Internal Server Error" description="" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.PROFILES_BALANCE_READ` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|------------|--------|----------|------------------------------------------------| +| `username` | string | Yes | The name of the user for whom to fetch the balance | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +"1000.5" ``` -{% endswagger-response %} -{% endswagger %} + +The balance is returned as a JSON string representing the account balance in HBAR. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/profile-apis/user-account-information.md b/docs/profile-apis/user-account-information.md index 841219d2f5..ee1f523eb1 100644 --- a/docs/profile-apis/user-account-information.md +++ b/docs/profile-apis/user-account-information.md @@ -1,51 +1,49 @@ # User Account Information -### RETURNS USER'S ACCOUNT INFORMATION +**`GET /api/v1/profiles/{username}/`** -{% swagger method="get" path="" baseUrl="/profiles/{username}" summary="Returns user account info" %} -{% swagger-description %} -Returns user account information. For users with the Standard Registry role it also returns address book and VC document information -{% endswagger-description %} +Returns account information for the specified user, including DID, Hedera account details, and VC documents. For users with the Standard Registry role it also returns address book and VC document information. -{% swagger-parameter in="path" name="username" type="String" required="true" %} -The name of the user for whom to fetch the information -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/User' -} -``` -{% endswagger-response %} +**Permission:** `Permissions.PROFILES_USER_READ` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +### Path Parameters + +| Parameter | Type | Required | Description | +|------------|--------|----------|--------------------------------------------------| +| `username` | string | Yes | The name of the user for whom to fetch the information | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "username": "example_user", + "role": "STANDARD_REGISTRY", + "did": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "hederaAccountId": "0.0.4532001", + "confirmed": true, + "failed": false, + "topic": "0.0.1234567", + "didDocument": {}, + "vcDocument": {} } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/profile-apis/validate-did-document.md b/docs/profile-apis/validate-did-document.md new file mode 100644 index 0000000000..17106a5de3 --- /dev/null +++ b/docs/profile-apis/validate-did-document.md @@ -0,0 +1,61 @@ +# Validate DID Document + +**`POST /profiles/did-document/validate`** + +Validates the format and structure of a DID document. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.PROFILES_USER_UPDATE` + +--- + +## Request + +### Request Body + +A DID document object following the W3C DID specification. + +```json +{ + "@context": ["https://www.w3.org/ns/did/v1"], + "id": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "verificationMethod": [ + { + "id": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001#did-root-key", + "type": "Ed25519VerificationKey2018", + "controller": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV" + } + ] +} +``` + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "valid": true, + "error": null +} +``` + +| Field | Type | Description | +|-------|------|-------------| +| `valid` | boolean | Whether the DID document is valid | +| `error` | string \| null | Error message if invalid | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Request body is empty | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/profile-apis/validate-did-keys.md b/docs/profile-apis/validate-did-keys.md new file mode 100644 index 0000000000..fb37e93409 --- /dev/null +++ b/docs/profile-apis/validate-did-keys.md @@ -0,0 +1,72 @@ +# Validate DID Keys + +**`POST /profiles/did-keys/validate`** + +Validates the keys within a DID document by checking that the provided private keys correspond to the public keys declared in the document. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.PROFILES_USER_UPDATE` + +--- + +## Request + +### Request Body + +```json +{ + "document": { + "@context": ["https://www.w3.org/ns/did/v1"], + "id": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "verificationMethod": [ + { + "id": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001#did-root-key", + "type": "Ed25519VerificationKey2018", + "controller": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV" + } + ] + }, + "keys": [ + { + "id": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001#did-root-key", + "privateKeyBase58": "4mhhQT2UKa..." + } + ] +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `document` | object | Yes | The DID document to validate | +| `keys` | array | Yes | Array of key objects with `id` and `privateKeyBase58` | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "valid": true, + "error": null +} +``` + +| Field | Type | Description | +|-------|------|-------------| +| `valid` | boolean | Whether all keys are valid | +| `error` | string \| null | Error message if validation fails | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Body, document, or keys field is empty | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/schema-creation-using-the-guardian-apis/README.md b/docs/schema-creation-using-the-guardian-apis/README.md new file mode 100644 index 0000000000..ff21082bdc --- /dev/null +++ b/docs/schema-creation-using-the-guardian-apis/README.md @@ -0,0 +1,47 @@ +# Schema Creation APIs + +**Base URL:** `/api/v1` + +These APIs allow Standard Registry users to manage schemas — create, update, publish, import, export, and delete schemas associated with Guardian policies. + +**Authentication:** All endpoints require a valid JWT Bearer token (`Authorization: Bearer `). Obtain a token via `POST /accounts/login`. + +--- + +## Endpoints + +| Method | Endpoint | Description | Auth Required | +|--------|----------|-------------|---------------| +| GET | `/schemas` | List all schemas (paginated) | Yes | +| GET | `/schema/{schemaId}` | Get schema by ID | Yes | +| GET | `/schemas/{topicId}` | List schemas by topic | Yes | +| POST | `/schemas/{topicId}` | Create new schema under a topic | Yes | +| PUT | `/schemas/` | Update an existing schema | Yes | +| DELETE | `/schemas/{schemaId}` | Delete a schema | Yes | +| PUT | `/schemas/{schemaId}/publish` | Publish schema to IPFS | Yes | +| GET | `/schemas/{schemaId}/export/message` | Export schema message IDs | Yes | +| GET | `/schemas/{schemaId}/export/file` | Export schema as zip file | Yes | +| POST | `/schemas/{topicId}/import/message` | Import schema from IPFS | Yes | +| POST | `/schemas/{topicId}/import/file` | Import schema from zip file | Yes | +| POST | `/schemas/import/message/preview` | Preview schema from IPFS before import | Yes | +| POST | `/schemas/import/file/preview` | Preview schema from zip before import | Yes | + +--- + +## Endpoint Details + +* [Listing of Schema](creation-of-a-schema-1.md) — `GET /schemas` +* [Returning Schema by SchemaID](returning-schema-by-schemaid.md) — `GET /schema/{schemaId}` +* [Returns All Schemas Related to the Topic](returns-all-schemas-related-to-the-topic.md) — `GET /schemas/{topicId}` +* [Creation of Schema Related to the Topic](creation-of-schema-related-to-the-topic.md) — `POST /schemas/{topicId}` +* [Updating Schema](updating-schema.md) — `PUT /schemas/` +* [Deleting a Schema](deleting-a-schema.md) — `DELETE /schemas/{schemaId}` +* [Publishing Schema Based on Schema ID](publishing-schema-based-on-schema-id.md) — `PUT /schemas/{schemaId}/publish` +* [Export Schema Message IDs](export-a-schema.md) — `GET /schemas/{schemaId}/export/message` +* [Export Schema as Zip](export-a-schema-1.md) — `GET /schemas/{schemaId}/export/file` +* [Import Schema from IPFS](importing-schema-from-ipfs.md) — `POST /schemas/{topicId}/import/message` +* [Import Schema from Zip](importing-zip-file-containing-schema.md) — `POST /schemas/{topicId}/import/file` +* [Schema Preview from IPFS](schema-preview-from-ipfs.md) — `POST /schemas/import/message/preview` +* [Schema Preview from Zip](schema-preview-from-zip.md) — `POST /schemas/import/file/preview` + +See [Prerequisite Steps](../policy-creation-using-the-guardian-apis/prerequesite-steps.md) for authentication setup. diff --git a/docs/schema-creation-using-the-guardian-apis/creation-of-a-schema-1.md b/docs/schema-creation-using-the-guardian-apis/creation-of-a-schema-1.md index df9e3d605f..55d6cf13ff 100644 --- a/docs/schema-creation-using-the-guardian-apis/creation-of-a-schema-1.md +++ b/docs/schema-creation-using-the-guardian-apis/creation-of-a-schema-1.md @@ -1,62 +1,59 @@ -# Listing of Schema - -### SCHEMA LISTING - -{% swagger method="get" path="" baseUrl="/schemas" summary="Returns all schemas" %} -{% swagger-description %} -Returns all schemas -{% endswagger-description %} - -{% swagger-parameter in="query" name="pageIndex" type="Integer" %} -The number of pages to skip before starting to collect the result set -{% endswagger-parameter %} - -{% swagger-parameter in="query" type="Integer" name="pageSize" %} -The numbers of items to return -{% endswagger-parameter %} - -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - headers: - x-total-count: - schema: - type: integer - description: Total items in the collection. - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/Schema' -} -``` -{% endswagger-response %} +# Listing of Schemas -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +**`GET /api/v1/schemas`** -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} - -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} +Returns a paginated list of all schemas owned by the authenticated Standard Registry user. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.SCHEMAS_SCHEMA_READ` + +--- + +## Request + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `pageIndex` | number | No | 0 | Zero-based page index (number of pages to skip) | +| `pageSize` | number | No | 20 | Number of items to return per page | +| `category` | string | No | — | Schema category filter (e.g. `POLICY`) | +| `policyId` | string | No | — | Filter schemas by policy ID | +| `moduleId` | string | No | — | Filter schemas by module ID | +| `toolId` | string | No | — | Filter schemas by tool ID | +| `topicId` | string | No | — | Filter schemas by topic ID | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +The response includes an `X-Total-Count` header containing the total number of matching schemas. + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Carbon Offset Schema", + "description": "Schema for carbon offset reporting", + "entity": "VC", + "status": "PUBLISHED", + "version": "1.0.0", + "topicId": "0.0.1234567", + "owner": "example_user" + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/schema-creation-using-the-guardian-apis/creation-of-schema-related-to-the-topic.md b/docs/schema-creation-using-the-guardian-apis/creation-of-schema-related-to-the-topic.md index 1a5671bfb3..64312060fa 100644 --- a/docs/schema-creation-using-the-guardian-apis/creation-of-schema-related-to-the-topic.md +++ b/docs/schema-creation-using-the-guardian-apis/creation-of-schema-related-to-the-topic.md @@ -1,54 +1,76 @@ -# Creation of Schema related to the topic +# Creation of Schema Related to the Topic -{% swagger method="post" path="" baseUrl="/schemas/{topicId}" summary="Creates a schema related to the topic (policy)" %} -{% swagger-description %} -Creates new schema. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /api/v1/schemas/{topicId}`** -{% swagger-parameter in="path" name="topicId" type="String" required="true" %} -Topic ID -{% endswagger-parameter %} +Creates a new schema under the specified Hedera topic. Only users with the Standard Registry role are allowed to make this request. -{% swagger-parameter in="body" required="true" type="Object" %} -Object that contains a valid schema -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="201: Created" description="Successful Operation" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +**Permission:** `Permissions.SCHEMAS_SCHEMA_CREATE` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `topicId` | string | Yes | The Hedera topic ID under which to create the schema (e.g. `0.0.1234567`) | -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +### Request Body + +```json { - // Response + "name": "Carbon Offset Schema", + "description": "Schema for carbon offset reporting", + "entity": "VC", + "category": "POLICY", + "document": { + "$schema": "http://json-schema.org/draft-07/schema", + "type": "object", + "properties": {} + } } ``` -{% endswagger-response %} -{% swagger-response status="422: Unprocessable Entity" description="Unprocessable Entity" %} +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | Yes | Human-readable name of the schema | +| `description` | string | No | Description of the schema | +| `entity` | string | Yes | Schema entity type (e.g. `VC`) | +| `category` | string | No | Schema category — defaults to `POLICY` | +| `document` | object | Yes | Valid JSON Schema document | -{% endswagger-response %} +--- -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} +## Response + +### Success Response + +**Status:** `201 Created` + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Carbon Offset Schema", + "description": "Schema for carbon offset reporting", + "entity": "VC", + "status": "DRAFT", + "version": "", + "topicId": "0.0.1234567", + "owner": "example_user" + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Invalid schema structure or duplicate key | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/schema-creation-using-the-guardian-apis/deleting-a-schema.md b/docs/schema-creation-using-the-guardian-apis/deleting-a-schema.md index aa58f4e44b..abf736d438 100644 --- a/docs/schema-creation-using-the-guardian-apis/deleting-a-schema.md +++ b/docs/schema-creation-using-the-guardian-apis/deleting-a-schema.md @@ -1,61 +1,54 @@ # Deleting a Schema -### DELETING SCHEMA BASED ON SCHEMA ID +**`DELETE /api/v1/schemas/{schemaId}`** -{% swagger method="delete" path="" baseUrl="/schema/{schemaID}" summary="Deletes the schema" %} -{% swagger-description %} -Deletes the schema with the provided schema ID. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +Deletes the schema with the specified ID. Only users with the Standard Registry role are allowed to make this request. Published or demo-mode schemas cannot be deleted. -{% swagger-parameter in="path" type="String" name="schemaID" required="true" %} -Schema ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/Schema' -} -``` -{% endswagger-response %} +**Permission:** `Permissions.SCHEMAS_SCHEMA_DELETE` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="422: Unprocessable Entity" description="" %} +### Path Parameters +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `schemaId` | string | Yes | The internal database ID of the schema to delete | -``` -Schema is published. -``` -{% endswagger-response %} +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `includeChildren` | boolean | No | `false` | When `true`, also deletes all child schemas | + +--- + +## Response + +### Success Response -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +**Status:** `200 OK` + +The deletion is processed asynchronously. The response contains a task object. + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Delete schema" } ``` -{% endswagger-response %} -{% endswagger %} + +Poll `GET /tasks/{taskId}` to retrieve the result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions or schema is owned by another user | +| `404 Not Found` | Schema with the provided ID does not exist | +| `422 Unprocessable Entity` | Schema is already published or imported in demo mode | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/schema-creation-using-the-guardian-apis/export-a-schema-1.md b/docs/schema-creation-using-the-guardian-apis/export-a-schema-1.md index f988c438fc..f282ea93ab 100644 --- a/docs/schema-creation-using-the-guardian-apis/export-a-schema-1.md +++ b/docs/schema-creation-using-the-guardian-apis/export-a-schema-1.md @@ -1,52 +1,38 @@ -# Export Files from Schema - -### [NextCreation of Schema related to the topic](https://app.gitbook.com/o/-LuC734MpqlgwA6zyhAO/s/bOsLGPRQ1YXxw4wDcVrE/\~/changes/334/guardian/standard-registry/schemas/schema-creation-using-apis/creation-of-schema-related-to-the-topic)EXPORTING SCHEMA FILES FOR THE SCHEMA - -{% swagger method="post" path="" baseUrl="/schemas/{schemaId}/export/file" summary="Return zip file with schemas" %} -{% swagger-description %} -Returns schema files for the schemas. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} - -{% swagger-parameter in="path" name="schemaID" type="String" required="true" %} -Selected schema ID -{% endswagger-parameter %} - -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - -} -``` -{% endswagger-response %} - -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} - -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} - -{% swagger-response status="422: Unprocessable Entity" description="Unprocessable Entity" %} - -{% endswagger-response %} - -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} -``` -{% endswagger-response %} -{% endswagger %} +# Export Schema as Zip File + +**`GET /api/v1/schemas/{schemaId}/export/file`** + +Returns a zip archive containing the schema files for the specified schema. Only users with the Standard Registry role are allowed to make this request. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.SCHEMAS_SCHEMA_READ` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `schemaId` | string | Yes | The internal database ID of the schema to export | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +The response body is a binary zip file (`application/zip`). The `Content-Disposition` header is set to `attachment; filename=`. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Schema cannot be exported | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/schema-creation-using-the-guardian-apis/export-a-schema.md b/docs/schema-creation-using-the-guardian-apis/export-a-schema.md index ddb1f8f626..65636de541 100644 --- a/docs/schema-creation-using-the-guardian-apis/export-a-schema.md +++ b/docs/schema-creation-using-the-guardian-apis/export-a-schema.md @@ -1,51 +1,47 @@ -# Export message IDs of Schema +# Export Schema Message IDs -### EXPORTING HEDERA MESSAGED IDS OF PUBLISHED SCHEMA +**`GET /api/v1/schemas/{schemaId}/export/message`** -{% swagger method="post" path="" baseUrl="/schemas/{schemaId}/export/message" summary="Hedera message IDs of published schemas" %} -{% swagger-description %} -Returns Hedera message IDs of the published schemas, these messages contain IPFS CIDs of these schema files. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +Returns the Hedera message ID of the published schema. The message contains the IPFS CID of the schema file. Only users with the Standard Registry role are allowed to make this request. -{% swagger-parameter in="path" name="schemaID" type="String" required="true" %} -Selected schema ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: "#/components/schemas/ExportSchema" -} -``` -{% endswagger-response %} +**Permission:** `Permissions.SCHEMAS_SCHEMA_READ` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `schemaId` | string | Yes | The internal database ID of the schema to export | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "id": "63e3e5e8a01b3c001234abcd", + "name": "Carbon Offset Schema", + "description": "Schema for carbon offset reporting", + "version": "1.0.0", + "messageId": "1234567890.000000001", + "owner": "example_user" } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Schema cannot be exported (e.g. not yet published) | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/schema-creation-using-the-guardian-apis/importing-schema-from-ipfs.md b/docs/schema-creation-using-the-guardian-apis/importing-schema-from-ipfs.md index 67215d8548..ee63352a0e 100644 --- a/docs/schema-creation-using-the-guardian-apis/importing-schema-from-ipfs.md +++ b/docs/schema-creation-using-the-guardian-apis/importing-schema-from-ipfs.md @@ -1,59 +1,65 @@ # Importing Schema from IPFS -{% swagger method="post" path="" baseUrl="/schemas/{topicId}/import/message" summary="Imports schemas from a message for the selected topic (policy)" %} -{% swagger-description %} -Imports new schema from IPFS into the local DB. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /schemas/{topicId}/import/message`** -{% swagger-parameter in="path" name="topicID" type="String" required="true" %} -Topic ID -{% endswagger-parameter %} +Imports a new schema from IPFS into the local database for the specified topic. -{% swagger-parameter in="body" type="Object" required="true" %} -Object that contains the identifier of the Hedera message which contains the IPFS CID of the schema. -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="201: Created" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/Schema' -} -``` -{% endswagger-response %} +**Permission:** `Permissions.SCHEMAS_SCHEMA_CREATE` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `topicId` | string | Yes | The Hedera topic ID to import the schema under (e.g. `0.0.4532001`) | -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +### Request Body + +```json { - // Response + "messageId": "1680000000.000000001" } ``` -{% endswagger-response %} -{% swagger-response status="422: Unprocessable Entity" description="Unprocessable Entity" %} +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `messageId` | string | Yes | The Hedera message ID containing the IPFS CID of the schema | -{% endswagger-response %} +--- -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} +## Response + +### Success Response + +**Status:** `201 Created` + +The response includes an `X-Total-Count` header with the total number of policy schemas. + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Carbon Offset Schema", + "entity": "VC", + "status": "PUBLISHED", + "version": "1.0.0", + "topicId": "0.0.4532001", + "owner": "example_user" + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Message ID is missing or invalid | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/schema-creation-using-the-guardian-apis/importing-zip-file-containing-schema.md b/docs/schema-creation-using-the-guardian-apis/importing-zip-file-containing-schema.md index 00bfed3d51..e9a921b4ef 100644 --- a/docs/schema-creation-using-the-guardian-apis/importing-zip-file-containing-schema.md +++ b/docs/schema-creation-using-the-guardian-apis/importing-zip-file-containing-schema.md @@ -1,59 +1,59 @@ -# Importing Zip file containing Schema - -{% swagger method="post" path="" baseUrl="/schemas/{topicId}/import/file" summary="Imports schemas from a file for the selected topic (policy)" %} -{% swagger-description %} -Imports new schema from a zip file into the local DB. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} - -{% swagger-parameter in="path" name="topicId" type="Integer" required="true" %} -Topic ID -{% endswagger-parameter %} - -{% swagger-parameter in="body" type="file" required="true" %} -A zip file containing schema to be imported -{% endswagger-parameter %} - -{% swagger-response status="201: Created" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/Schema' -} -``` -{% endswagger-response %} +# Importing Zip File Containing Schema -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +**`POST /schemas/{topicId}/import/file`** -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +Imports a new schema from a zip file into the local database for the specified topic. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.SCHEMAS_SCHEMA_CREATE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `topicId` | string | Yes | The Hedera topic ID to import the schema under (e.g. `0.0.4532001`) | -{% swagger-response status="422: Unprocessable Entity" description="Unprocessable Entity" %} +### Request Body -{% endswagger-response %} +The request body must be the raw binary content of a `.zip` file exported from Guardian. -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} +**Content-Type:** `application/octet-stream` + +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +The response includes an `X-Total-Count` header with the total number of policy schemas. + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Carbon Offset Schema", + "entity": "VC", + "status": "DRAFT", + "version": "", + "topicId": "0.0.4532001", + "owner": "example_user" + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | File is missing or invalid | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/schema-creation-using-the-guardian-apis/publishing-schema-based-on-schema-id.md b/docs/schema-creation-using-the-guardian-apis/publishing-schema-based-on-schema-id.md index a20fce450c..298b96fa05 100644 --- a/docs/schema-creation-using-the-guardian-apis/publishing-schema-based-on-schema-id.md +++ b/docs/schema-creation-using-the-guardian-apis/publishing-schema-based-on-schema-id.md @@ -1,61 +1,66 @@ -# Publishing Schema based on Schema ID +# Publishing Schema Based on Schema ID -### PUBLISHING SCHEMA BASED ON SCHEMA ID +**`PUT /api/v1/schemas/{schemaId}/publish`** -{% swagger method="put" path="" baseUrl="/schemas/{schemaId}/publish" summary="Publishes the schema" %} -{% swagger-description %} -Publishes the schema with the provided (internal) schema ID onto IPFS, sends a message featuring IPFS CID into the corresponding Hedera topic. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +Publishes the schema with the specified internal ID onto IPFS and sends a message containing the IPFS CID to the corresponding Hedera topic. Only users with the Standard Registry role are allowed to make this request. -{% swagger-parameter in="path" name="schemaID" type="String" required="true" %} -Schema ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-parameter in="body" type="Object" required="true" name="version" %} -Object that contains policy version -{% endswagger-parameter %} +**Permission:** `Permissions.SCHEMAS_SCHEMA_REVIEW` -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/Schema' -} -``` -{% endswagger-response %} +--- -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `schemaId` | string | Yes | The internal database ID of the schema to publish | + +### Request Body -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +```json { - // Response + "version": "1.0.0" } ``` -{% endswagger-response %} -{% swagger-response status="422: Unprocessable Entity" description="" %} +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `version` | string | Yes | The version string to assign to this published schema (e.g. `1.0.0`) | -{% endswagger-response %} +--- -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} +## Response + +### Success Response + +**Status:** `200 OK` + +The response includes an `X-Total-Count` header with the total number of policy schemas. + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Carbon Offset Schema", + "status": "PUBLISHED", + "version": "1.0.0", + "topicId": "0.0.1234567", + "messageId": "1234567890.000000001", + "owner": "example_user" + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions or schema is owned by another user | +| `404 Not Found` | Schema with the provided ID does not exist | +| `422 Unprocessable Entity` | Schema is already published, in demo mode, or version already exists | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/schema-creation-using-the-guardian-apis/returning-schema-by-schemaid.md b/docs/schema-creation-using-the-guardian-apis/returning-schema-by-schemaid.md index 6e78f83d71..6ff5323a14 100644 --- a/docs/schema-creation-using-the-guardian-apis/returning-schema-by-schemaid.md +++ b/docs/schema-creation-using-the-guardian-apis/returning-schema-by-schemaid.md @@ -1,49 +1,50 @@ -# Returning Schema by SchemaID +# Returning Schema by Schema ID -{% swagger method="get" path="" baseUrl="/schema/{schemaId}" summary="Returns schema by schema ID" %} -{% swagger-description %} -Returns schema by schema ID -{% endswagger-description %} +**`GET /api/v1/schema/{schemaId}`** -{% swagger-parameter in="path" name="schemaId" type="String" required="true" %} -Schema ID -{% endswagger-parameter %} +Returns a single schema object identified by its internal database ID. -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Schema' -} -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `schemaId` | string | Yes | The internal database ID of the schema | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Carbon Offset Schema", + "description": "Schema for carbon offset reporting", + "entity": "VC", + "status": "PUBLISHED", + "version": "1.0.0", + "topicId": "0.0.1234567", + "owner": "example_user", + "document": {}, + "context": {} } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `404 Not Found` | Schema does not exist or is not accessible | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/schema-creation-using-the-guardian-apis/returns-all-schemas-related-to-the-topic.md b/docs/schema-creation-using-the-guardian-apis/returns-all-schemas-related-to-the-topic.md index dc6e8bf075..3f27536ce0 100644 --- a/docs/schema-creation-using-the-guardian-apis/returns-all-schemas-related-to-the-topic.md +++ b/docs/schema-creation-using-the-guardian-apis/returns-all-schemas-related-to-the-topic.md @@ -1,64 +1,61 @@ -# Returns all Schemas related to the topic - -{% swagger method="get" path="" baseUrl=" /schemas/{topicId}" summary="Returns schemas related to the topic (policy)" %} -{% swagger-description %} -Returns all schemas by topicId. -{% endswagger-description %} - -{% swagger-parameter in="path" name="topicId" type="Integer" required="true" %} -Topic ID -{% endswagger-parameter %} - -{% swagger-parameter in="query" name="pageIndex" type="Integer" %} -The number of pages to skip before starting to collect the result set -{% endswagger-parameter %} - -{% swagger-parameter in="query" type="Integer" name="pageSize" %} -The numbers of items to return -{% endswagger-parameter %} - -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - headers: - x-total-count: - schema: - type: integer - description: Total items in the collection. - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/Schema' -} -``` -{% endswagger-response %} +# Returns All Schemas Related to the Topic -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +**`GET /api/v1/schemas/{topicId}`** -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} - -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} +Returns a paginated list of all schemas associated with the specified Hedera topic ID. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.SCHEMAS_SCHEMA_READ` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `topicId` | string | Yes | The Hedera topic ID to filter schemas by (e.g. `0.0.1234567`) | + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `pageIndex` | number | No | 0 | Zero-based page index (number of pages to skip) | +| `pageSize` | number | No | 20 | Number of items to return per page | +| `category` | string | No | — | Schema category filter (e.g. `POLICY`) | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +The response includes an `X-Total-Count` header with the total number of matching schemas. + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Carbon Offset Schema", + "description": "Schema for carbon offset reporting", + "entity": "VC", + "status": "PUBLISHED", + "version": "1.0.0", + "topicId": "0.0.1234567", + "owner": "example_user" + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/schema-creation-using-the-guardian-apis/schema-preview-from-ipfs.md b/docs/schema-creation-using-the-guardian-apis/schema-preview-from-ipfs.md index ff9ccfb98f..91c7af7d80 100644 --- a/docs/schema-creation-using-the-guardian-apis/schema-preview-from-ipfs.md +++ b/docs/schema-creation-using-the-guardian-apis/schema-preview-from-ipfs.md @@ -1,53 +1,60 @@ # Schema Preview from IPFS -### PREVIEWING SCHEMA FROM IPFS FILE +**`POST /schemas/import/message/preview`** -{% swagger method="post" path="" baseUrl="/schemas/import/message/preview" summary="Schema preview from IPFS" %} -{% swagger-description %} -Previews the schema from IPFS without loading it into the local DB. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +Previews the schema from IPFS without importing it into the local database. -{% swagger-parameter in="body" name="" type="Object" required="true" %} -Object that contains the identifier of the Hedera message which contains the IPFS CID of the schema -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/Schema' -} -``` -{% endswagger-response %} +**Permission:** `Permissions.SCHEMAS_SCHEMA_CREATE` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- + +## Request -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +### Request Body + +```json { - // Response + "messageId": "1680000000.000000001" } ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `messageId` | string | Yes | The Hedera message ID containing the IPFS CID of the schema | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Carbon Offset Schema", + "entity": "VC", + "version": "1.0.0", + "document": { + "$id": "#CarbonOffset", + "$schema": "http://json-schema.org/draft-07/schema", + "type": "object", + "properties": {} + } + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Message ID is missing | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/schema-creation-using-the-guardian-apis/schema-preview-from-zip.md b/docs/schema-creation-using-the-guardian-apis/schema-preview-from-zip.md index 6da35c15cb..b89d4c2941 100644 --- a/docs/schema-creation-using-the-guardian-apis/schema-preview-from-zip.md +++ b/docs/schema-creation-using-the-guardian-apis/schema-preview-from-zip.md @@ -1,53 +1,54 @@ # Schema Preview from Zip -### PREVIEWING SCHEMA FROM ZIP FILE - -{% swagger method="post" path="" baseUrl="/schemas/import/file/preview" summary="Schema preview from a zip file" %} -{% swagger-description %} -Previews the schema from a zip file. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} - -{% swagger-parameter in="body" name="" type="" required="true" %} -A zip file containing the schema to be viewed -{% endswagger-parameter %} - -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/Schema' -} -``` -{% endswagger-response %} +**`POST /schemas/import/file/preview`** -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +Previews the schema from a zip file without importing it into the local database. -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} - -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.SCHEMAS_SCHEMA_CREATE` + +--- + +## Request + +### Request Body + +The request body must be the raw binary content of a `.zip` file containing schema files. + +**Content-Type:** `application/octet-stream` + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Carbon Offset Schema", + "entity": "VC", + "version": "1.0.0", + "document": { + "$id": "#CarbonOffset", + "$schema": "http://json-schema.org/draft-07/schema", + "type": "object", + "properties": {} + } + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | File is missing or empty | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/schema-creation-using-the-guardian-apis/updating-schema.md b/docs/schema-creation-using-the-guardian-apis/updating-schema.md index 41c9041de0..5e436a62f5 100644 --- a/docs/schema-creation-using-the-guardian-apis/updating-schema.md +++ b/docs/schema-creation-using-the-guardian-apis/updating-schema.md @@ -1,61 +1,73 @@ # Updating Schema -### UPDATING SCHEMA BASED ON SCHEMA ID +**`PUT /api/v1/schemas`** -{% swagger method="put" path="" baseUrl="/schemas/{schemaId}" summary="Updates the schema" %} -{% swagger-description %} -Updates the schema matching the id in the request body. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +Updates an existing schema. The schema to update is identified by the `id` field in the request body. Only users with the Standard Registry role are allowed to make this request. Published or demo-mode schemas cannot be updated. -{% swagger-parameter in="path" name="schemaID" type="String" required="true" %} -Schema ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-parameter in="body" type="schema" required="true" %} -Object that contains a valid schema including the id of the schema that is to be update -{% endswagger-parameter %} +**Permission:** `Permissions.SCHEMAS_SCHEMA_UPDATE` -{% swagger-response status="200: OK" description="Succesful Operation" %} -```javascript -{ - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/Schema' -} -``` -{% endswagger-response %} +--- -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request + +### Request Body -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +```json { - // Response + "id": "63e3e5e8a01b3c001234abcd", + "name": "Updated Carbon Offset Schema", + "description": "Updated description for carbon offset reporting", + "entity": "VC", + "category": "POLICY", + "document": { + "$schema": "http://json-schema.org/draft-07/schema", + "type": "object", + "properties": {} + } } ``` -{% endswagger-response %} -{% swagger-response status="422: Unprocessable Entity" description="" %} +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `id` | string | Yes | Internal database ID of the schema to update | +| `name` | string | No | Updated human-readable name | +| `description` | string | No | Updated description | +| `entity` | string | No | Schema entity type | +| `category` | string | No | Schema category | +| `document` | object | No | Updated JSON Schema document | -{% endswagger-response %} +--- -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} +## Response + +### Success Response + +**Status:** `200 OK` + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Updated Carbon Offset Schema", + "description": "Updated description for carbon offset reporting", + "entity": "VC", + "status": "DRAFT", + "version": "", + "topicId": "0.0.1234567", + "owner": "example_user" + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions or schema is owned by another user | +| `404 Not Found` | Schema with the provided ID does not exist | +| `422 Unprocessable Entity` | Schema is already published or imported in demo mode | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/schema-related-apis-for-asynchronous-execution/README.md b/docs/schema-related-apis-for-asynchronous-execution/README.md new file mode 100644 index 0000000000..8255fffe71 --- /dev/null +++ b/docs/schema-related-apis-for-asynchronous-execution/README.md @@ -0,0 +1,29 @@ +# Schema APIs — Asynchronous Execution + +**Base URL:** `/api/v1/schemas/push` + +Provides asynchronous endpoints for creating, publishing, and importing schemas. All endpoints return `{ taskId, expectation }` with status 202 Accepted. Poll `GET /tasks/{taskId}` for the result. + +**Authentication:** All endpoints require a valid JWT Bearer token (`Authorization: Bearer `). Obtain a token via `POST /accounts/login`. + +--- + +## Endpoints + +| Method | Endpoint | Description | Auth Required | +|--------|----------|-------------|---------------| +| POST | `/schemas/push/{topicId}` | Creates a new schema within the specified topic (async). Poll `GET /tasks/{taskId}` for result. | Yes | +| PUT | `/schemas/push/{schemaId}/publish` | Publishes a schema to IPFS (async). Poll `GET /tasks/{taskId}` for result. | Yes | +| POST | `/schemas/push/{topicId}/import/file` | Imports a schema from a zip file (async). Poll `GET /tasks/{taskId}` for result. | Yes | +| POST | `/schemas/push/{topicId}/import/message` | Imports a schema from IPFS via Hedera message ID (async). Poll `GET /tasks/{taskId}` for result. | Yes | +| POST | `/schemas/push/import/message/preview` | Previews a schema from IPFS without importing (async). Poll `GET /tasks/{taskId}` for result. | Yes | + +--- + +## Endpoint Details + +* [Creation of Schema](creation-of-schema.md) — `POST /schemas/push/{topicId}` +* [Publishing Schema](publishing-schema.md) — `PUT /schemas/push/{schemaId}/publish` +* [Importing Schema from .zip](importing-schema-from-.zip.md) — `POST /schemas/push/{topicId}/import/file` +* [Importing Schema from IPFS](importing-schema-from-ipfs.md) — `POST /schemas/push/{topicId}/import/message` +* [Previews the Schema from IPFS](previews-the-schema-from-ipfs.md) — `POST /schemas/push/import/message/preview` diff --git a/docs/schema-related-apis-for-asynchronous-execution/creation-of-schema.md b/docs/schema-related-apis-for-asynchronous-execution/creation-of-schema.md index c620865309..fc1d688138 100644 --- a/docs/schema-related-apis-for-asynchronous-execution/creation-of-schema.md +++ b/docs/schema-related-apis-for-asynchronous-execution/creation-of-schema.md @@ -1,53 +1,62 @@ -# Creation of Schema +# Creation of Schema (Async) -{% swagger method="post" path="" baseUrl="/schemas/push/{topicId}" summary="Create new schema." %} -{% swagger-description %} -Creates new schema. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /schemas/push/{topicId}`** -{% swagger-parameter in="path" name="topicId" type="String" required="true" %} -Topic ID -{% endswagger-parameter %} +Creates a new schema under the specified topic asynchronously. Returns a task ID immediately; poll `GET /tasks/{taskId}` for the result. -{% swagger-parameter in="body" required="true" %} -Object that contains a valid schema. -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="202: Accepted" description="Accepted" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Task' -} -``` -{% endswagger-response %} +**Permission:** `Permissions.SCHEMAS_SCHEMA_CREATE` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `topicId` | string | Yes | The Hedera topic ID under which to create the schema (e.g. `0.0.4532001`) | -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +### Request Body + +```json { - // Response + "name": "Carbon Offset Schema", + "description": "Schema for carbon offset reporting", + "entity": "VC", + "category": "POLICY", + "document": { + "$schema": "http://json-schema.org/draft-07/schema", + "type": "object", + "properties": {} + } } ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +The request body is a valid schema configuration object. + +--- + +## Response + +### Success Response + +**Status:** `202 Accepted` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Create schema" } ``` -{% endswagger-response %} -{% endswagger %} + +Poll `GET /tasks/{taskId}` to retrieve the result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/schema-related-apis-for-asynchronous-execution/importing-schema-from-.zip.md b/docs/schema-related-apis-for-asynchronous-execution/importing-schema-from-.zip.md index 4b34f939c8..af480bdd60 100644 --- a/docs/schema-related-apis-for-asynchronous-execution/importing-schema-from-.zip.md +++ b/docs/schema-related-apis-for-asynchronous-execution/importing-schema-from-.zip.md @@ -1,53 +1,51 @@ -# Importing Schema from .zip +# Importing Schema from Zip (Async) -{% swagger method="post" path="" baseUrl=" /schemas/push/{topicId}/import/file" summary="Imports new schema from a zip file." %} -{% swagger-description %} -Imports new schema from a zip file into the local DB. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /schemas/push/{topicId}/import/file`** -{% swagger-parameter in="body" type="String" required="true" %} -A zip file containing schema to be imported -{% endswagger-parameter %} +Imports a new schema from a zip file into the local database asynchronously. Returns a task ID immediately; poll `GET /tasks/{taskId}` for the result. -{% swagger-parameter in="path" name="topicId" type="String" required="true" %} -topic ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="202: Accepted" description="Accepted" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Task' -} -``` -{% endswagger-response %} +**Permission:** `Permissions.SCHEMAS_SCHEMA_CREATE` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `topicId` | string | Yes | The Hedera topic ID to import the schema under (e.g. `0.0.4532001`) | -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +### Request Body + +The request body must be the raw binary content of a `.zip` file exported from Guardian. + +**Content-Type:** `application/octet-stream` + +--- + +## Response + +### Success Response + +**Status:** `202 Accepted` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Import schema file" } ``` -{% endswagger-response %} -{% endswagger %} + +Poll `GET /tasks/{taskId}` to retrieve the result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | File is missing or empty | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/schema-related-apis-for-asynchronous-execution/importing-schema-from-ipfs.md b/docs/schema-related-apis-for-asynchronous-execution/importing-schema-from-ipfs.md index 6cc4521857..f874a477d4 100644 --- a/docs/schema-related-apis-for-asynchronous-execution/importing-schema-from-ipfs.md +++ b/docs/schema-related-apis-for-asynchronous-execution/importing-schema-from-ipfs.md @@ -1,54 +1,57 @@ -# Importing Schema from IPFS +# Importing Schema from IPFS (Async) -{% swagger method="post" path="" baseUrl="/schemas/push/{topicId}/import/message" summary="Imports new schema from IPFS." %} -{% swagger-description %} -Imports new schema from IPFS into the local DB. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /schemas/push/{topicId}/import/message`** -{% swagger-parameter in="body" required="true" type="String" name="messageId" %} -Object that contains the identifier of the Hedera message which contains the IPFS CID of the schema. -{% endswagger-parameter %} +Imports a new schema from IPFS into the local database asynchronously. Returns a task ID immediately; poll `GET /tasks/{taskId}` for the result. -{% swagger-parameter in="path" name="topicId" type="String" required="true" %} -Topic ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="202: Accepted" description="Accepted" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Task' -} -``` -{% endswagger-response %} +**Permission:** `Permissions.SCHEMAS_SCHEMA_CREATE` + +--- + +## Request -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `topicId` | string | Yes | The Hedera topic ID to import the schema under (e.g. `0.0.4532001`) | + +### Request Body + +```json { - // Response + "messageId": "1680000000.000000001" } ``` -{% endswagger-response %} -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `messageId` | string | Yes | The Hedera message ID containing the IPFS CID of the schema | + +--- + +## Response + +### Success Response + +**Status:** `202 Accepted` + +```json { - // Response + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Import schema message" } ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' +Poll `GET /tasks/{taskId}` to retrieve the result. -} -``` -{% endswagger-response %} -{% endswagger %} +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Message ID is missing | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/schema-related-apis-for-asynchronous-execution/previews-the-schema-from-ipfs.md b/docs/schema-related-apis-for-asynchronous-execution/previews-the-schema-from-ipfs.md index 0046ff2615..7af9826f3d 100644 --- a/docs/schema-related-apis-for-asynchronous-execution/previews-the-schema-from-ipfs.md +++ b/docs/schema-related-apis-for-asynchronous-execution/previews-the-schema-from-ipfs.md @@ -1,49 +1,51 @@ -# Previews the Schema from IPFS +# Previews the Schema from IPFS (Async) -{% swagger method="post" path="" baseUrl="/schemas/push/import/message/preview" summary="Schema preview from IPFS" %} -{% swagger-description %} -Previews the schema from IPFS without loading it into the local DB. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /schemas/push/import/message/preview`** -{% swagger-parameter in="body" required="true" type="String" name="messageId" %} -Object that contains the identifier of the Hedera message which contains the IPFS CID of the schema. -{% endswagger-parameter %} +Previews a schema from IPFS asynchronously without importing it into the local database. Returns a task ID immediately; poll `GET /tasks/{taskId}` for the result. -{% swagger-response status="202: Accepted" description="Accepted" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Task' -} -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +**Permission:** `Permissions.SCHEMAS_SCHEMA_CREATE` + +--- + +## Request + +### Request Body -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +```json { - // Response + "messageId": "1680000000.000000001" } ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `messageId` | string | Yes | The Hedera message ID containing the IPFS CID of the schema | + +--- + +## Response + +### Success Response + +**Status:** `202 Accepted` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Preview schema message" } ``` -{% endswagger-response %} -{% endswagger %} + +Poll `GET /tasks/{taskId}` to retrieve the preview result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Message ID is missing | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/schema-related-apis-for-asynchronous-execution/publishing-schema.md b/docs/schema-related-apis-for-asynchronous-execution/publishing-schema.md index f91b6ad596..d5635e4b09 100644 --- a/docs/schema-related-apis-for-asynchronous-execution/publishing-schema.md +++ b/docs/schema-related-apis-for-asynchronous-execution/publishing-schema.md @@ -1,53 +1,58 @@ -# Publishing Schema +# Publishing Schema (Async) -{% swagger method="put" path="" baseUrl="/schemas/push/{schemaId}/publish" summary="Publishes the schema with the provided (internal) schema ID onto IPFS, sends a message featuring IPFS CID into the corresponding Hedera topic." %} -{% swagger-description %} -Publishes the schema with the provided (internal) schema ID onto IPFS, sends a message featuring IPFS CID into the corresponding Hedera topic. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`PUT /schemas/push/{schemaId}/publish`** -{% swagger-parameter in="path" name="schemaID" type="String" required="true" %} -Schema ID -{% endswagger-parameter %} +Publishes the specified schema onto IPFS asynchronously, sending a message with its IPFS CID to the corresponding Hedera topic. Returns a task ID immediately; poll `GET /tasks/{taskId}` for the result. -{% swagger-parameter in="body" required="true" %} -Object that contains policy version. -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="202: Accepted" description="Accepted" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Task' -} -``` -{% endswagger-response %} +**Permission:** `Permissions.SCHEMAS_SCHEMA_REVIEW` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `schemaId` | string | Yes | The schema ID (MongoDB ObjectId, e.g. `63e3e5e8a01b3c001234abcd`) | -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +### Request Body + +```json { - // Response + "version": "1.0.0" } ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `version` | string | Yes | The version string to assign to the published schema (e.g. `1.0.0`) | + +--- + +## Response + +### Success Response + +**Status:** `202 Accepted` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Publish schema" } ``` -{% endswagger-response %} -{% endswagger %} + +Poll `GET /tasks/{taskId}` to retrieve the result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions or schema owned by another user | +| `404 Not Found` | Schema not found | +| `422 Unprocessable Entity` | Schema is already published or version already exists | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/settings-apis/README.md b/docs/settings-apis/README.md new file mode 100644 index 0000000000..91deddbb0b --- /dev/null +++ b/docs/settings-apis/README.md @@ -0,0 +1,27 @@ +# Settings APIs + +**Base URL:** `/api/v1/settings` + +These endpoints allow retrieval and configuration of Guardian system settings, including Hedera operator credentials, environment information, and package version details. + +**Authentication:** All endpoints require a valid JWT Bearer token (`Authorization: Bearer `). Obtain a token via `POST /accounts/login`. + +--- + +## Endpoints + +| Method | Endpoint | Description | Auth Required | +|--------|----------|-------------|---------------| +| POST | `/settings` | Set Guardian system settings | Yes | +| GET | `/settings` | Return current Guardian system settings | Yes | +| GET | `/settings/environment` | Return the current Hedera network environment name | Yes | +| GET | `/settings/about` | Return Guardian package version information | Yes | + +--- + +## Endpoint Details + +* [Adding Settings](adding-settings.md) +* [Displaying Current Settings](displaying-current-settings.md) +* [Returns Environment Name](returns-environment-name.md) +* [Returns Package Version](returns-package-version.md) diff --git a/docs/settings-apis/adding-settings.md b/docs/settings-apis/adding-settings.md index b785af47cd..7bfcc556ed 100644 --- a/docs/settings-apis/adding-settings.md +++ b/docs/settings-apis/adding-settings.md @@ -1,55 +1,45 @@ # Adding Settings -## SET SETTINGS +**`POST /settings/`** -{% swagger method="post" path="" baseUrl="/settings" summary="Set settings." %} -{% swagger-description %} -Set settings. For users with the Standard Registry role only. -{% endswagger-description %} +Sets Hedera operator credentials and other system settings. For Standard Registry users only. -{% swagger-parameter in="body" type="String" required="true" name="operatorID" %} -ID of the operator -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-parameter in="body" name="operatorKey" type="String" required="true" %} -Key of the operator -{% endswagger-parameter %} +**Permission:** `Permissions.SETTINGS_SETTINGS_UPDATE` -{% swagger-parameter in="body" name="nftApiKey" type="String" required="true" %} -API key of NFT -{% endswagger-parameter %} +--- -{% swagger-response status="201: Created" description="Created" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +### Request Body -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +```json { - // Response + "operatorAccountId": "0.0.4532001", + "operatorPrivateKey": "302e020100300506032b657004220420..." } ``` -{% endswagger-response %} -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript -{ - application/json: - schema: - $ref: '#/components/schemas/Error' -} -``` -{% endswagger-response %} -{% endswagger %} +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `operatorAccountId` | string | Yes | Hedera operator account ID (e.g. `0.0.4532001`) | +| `operatorPrivateKey` | string | Yes | Hedera operator private key | + +--- + +## Response + +### Success Response + +**Status:** `201 Created` + +No response body. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/settings-apis/displaying-current-settings.md b/docs/settings-apis/displaying-current-settings.md index ec19e29fae..13667523fe 100644 --- a/docs/settings-apis/displaying-current-settings.md +++ b/docs/settings-apis/displaying-current-settings.md @@ -1,50 +1,43 @@ # Displaying Current Settings -## DISPLAYS CURRENT SETTINGS +**`GET /settings/`** -{% swagger method="get" path="" baseUrl="/settings" summary="Returns current settings" %} -{% swagger-description %} -Returns current settings. For users with the Standard Registry role only -{% endswagger-description %} +Returns the current system settings. For Standard Registry users only. -{% swagger-response status="200: OK" description="Success Operation" %} -```javascript -{ - type: object - properties: - operatorId: - type: string - operatorKey: - type: string - nftApiKey: - type: string -} -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +**Permission:** `Permissions.SETTINGS_SETTINGS_READ` -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +## Request + +No request body or parameters required. + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json { - application/json: - schema: - $ref: '#/components/schemas/Error' + "operatorAccountId": "0.0.4532001", + "operatorPrivateKey": "302e020100300506032b657004220420..." } ``` -{% endswagger-response %} -{% endswagger %} + +| Field | Type | Description | +|-------|------|-------------| +| `operatorAccountId` | string | Hedera operator account ID | +| `operatorPrivateKey` | string | Hedera operator private key | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/settings-apis/returns-environment-name.md b/docs/settings-apis/returns-environment-name.md new file mode 100644 index 0000000000..7627ed001a --- /dev/null +++ b/docs/settings-apis/returns-environment-name.md @@ -0,0 +1,34 @@ +# Returns Environment Name + +**`GET /settings/environment`** + +Returns the name of the current Hedera network environment. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +--- + +## Request + +No request body or parameters required. + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +"testnet" +``` + +Possible values: `mainnet`, `testnet`, `previewnet`. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/settings-apis/returns-package-version.md b/docs/settings-apis/returns-package-version.md new file mode 100644 index 0000000000..3a7da1a1e1 --- /dev/null +++ b/docs/settings-apis/returns-package-version.md @@ -0,0 +1,37 @@ +# Returns Package Version + +**`GET /settings/about`** + +Returns the current Guardian package version. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.SETTINGS_SETTINGS_READ` + +--- + +## Request + +No request body or parameters required. + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "version": "3.0.0" +} +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/system-schemas-apis/README.md b/docs/system-schemas-apis/README.md new file mode 100644 index 0000000000..7ec167dfa6 --- /dev/null +++ b/docs/system-schemas-apis/README.md @@ -0,0 +1,31 @@ +# System Schemas APIs + +The System Schemas APIs provide endpoints for managing Guardian built-in system schemas, such as Standard Registry, User, Policy, and Token schemas that underpin the platform's own data structures. + +**Base URL:** `/api/v1/schemas/system` + +--- + +## Endpoints + +| Method | Endpoint | Description | Auth Required | +|--------|----------|-------------|---------------| +| **`POST`** | `/schemas/system/{username}` | Creates a new system schema | Yes | +| **`GET`** | `/schemas/system/{username}` | Returns system schemas by username | Yes | +| **`PUT`** | `/schemas/system/{schemaId}` | Updates the specified system schema | Yes | +| **`PUT`** | `/schemas/system/{schemaId}/active` | Makes the schema active (publishes it) | Yes | +| **`DELETE`** | `/schemas/system/{schemaId}` | Deletes the specified system schema (async) | Yes | +| **`GET`** | `/schemas/system/entity/{schemaEntity}` | Returns the active schema for the given entity type | Yes | +| **`GET`** | `/schemas/type/{schemaType}` | Returns schema by JSON document type string | Yes | + +--- + +## Endpoint Details + +* [Creates New System Schema](creates-new-system-schema.md) +* [Returns Schema by Username](returns-schema-by-username.md) +* [Updates the Schema](updates-the-schema.md) +* [Publishes the Schema (Make Active)](publishes-the-schema.md) +* [Delete System Schema](delete-system-schema.md) +* [Returns Schema by Entity Type](schema-type.md) +* [Returns Schema by Schema Type](returns-schema-by-type.md) diff --git a/docs/system-schemas-apis/creates-new-system-schema.md b/docs/system-schemas-apis/creates-new-system-schema.md index ad9ac18444..af95290b54 100644 --- a/docs/system-schemas-apis/creates-new-system-schema.md +++ b/docs/system-schemas-apis/creates-new-system-schema.md @@ -1,56 +1,71 @@ # Creates New System Schema -### CREATES NEW SYSTEM SCHEMA +**`POST /schemas/system/{username}`** -{% swagger method="post" path="" baseUrl="/schemas/system/{username}" summary="Creates new System Schema" %} -{% swagger-description %} -Creates new system schema. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +Creates a new system schema. Only users with the Standard Registry role are allowed to make this request. -{% swagger-parameter in="path" name="username" type="String" required="true" %} -Username -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-parameter in="body" required="true" %} -Object that contains valid Schema -{% endswagger-parameter %} +**Permission:** `Permissions.SCHEMAS_SYSTEM_SCHEMA_CREATE` -{% swagger-response status="201: Created" description="Successful Operation" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request + +### Path Parameters -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `username` | string | Yes | Username of the schema owner | + +### Request Body + +```json { - // Response + "name": "Example System Schema", + "description": "A system schema for standard registry data", + "entity": "STANDARD_REGISTRY", + "document": { + "$id": "#Example", + "$schema": "http://json-schema.org/draft-07/schema", + "type": "object", + "properties": {} + } } ``` -{% endswagger-response %} -{% swagger-response status="422: Unprocessable Entity" description="Unprocessable Entity" %} +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | Yes | Schema name | +| `description` | string | No | Schema description | +| `entity` | string | Yes | Entity type: `STANDARD_REGISTRY`, `USER`, `POLICY`, `MINT_TOKEN`, `WIPE_TOKEN`, `MINT_NFTOKEN` | +| `document` | object | Yes | JSON Schema definition | + +--- + +## Response -{% endswagger-response %} +### Success Response -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +**Status:** `201 Created` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "id": "63e3e5e8a01b3c001234abcd", + "name": "Example System Schema", + "entity": "STANDARD_REGISTRY", + "status": "DRAFT", + "system": true, + "active": false, + "owner": "example_user" } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Invalid schema data | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/system-schemas-apis/delete-system-schema.md b/docs/system-schemas-apis/delete-system-schema.md index 5116135f2f..403cf79735 100644 --- a/docs/system-schemas-apis/delete-system-schema.md +++ b/docs/system-schemas-apis/delete-system-schema.md @@ -1,53 +1,46 @@ # Delete System Schema -### DELETE THE SYSTEM SCHEMA WITH THE PROVIDED SCHEMA ID +**`DELETE /schemas/system/{schemaId}`** -{% swagger method="delete" path="" baseUrl="/schemas/system/{schemaId}" summary="Deletes the Schema" %} -{% swagger-description %} -Deletes the system schema with the provided Schema ID. Only users with the Standard Registry role are allowed to make a request. -{% endswagger-description %} +Deletes the system schema with the specified schema ID asynchronously. Only users with the Standard Registry role are allowed to make this request. -{% swagger-parameter in="path" name="schemaId" type="String" required="true" %} -SchemaID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="204: No Content" description="No Content" %} -```javascript -{ - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/Schema' -} -``` -{% endswagger-response %} +**Permission:** `Permissions.SCHEMAS_SYSTEM_SCHEMA_DELETE` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `schemaId` | string | Yes | The schema ID (MongoDB ObjectId, e.g. `63e3e5e8a01b3c001234abcd`) | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Delete schemas" } ``` -{% endswagger-response %} -{% endswagger %} + +Poll `GET /tasks/{taskId}` to retrieve the result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions or schema belongs to another user | +| `404 Not Found` | Schema not found | +| `422 Unprocessable Entity` | Schema is active and cannot be deleted | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/system-schemas-apis/publishes-the-schema.md b/docs/system-schemas-apis/publishes-the-schema.md index 184e46c12a..ec93c0eb60 100644 --- a/docs/system-schemas-apis/publishes-the-schema.md +++ b/docs/system-schemas-apis/publishes-the-schema.md @@ -1,71 +1,39 @@ -# Publishes the Schema +# Publishes the Schema (Make Active) -### PUBLISHES THE SCHEMA +**`PUT /schemas/system/{schemaId}/active`** -{% swagger method="put" path="" baseUrl="/schemas/{schemaId}/active" summary="Publishes the Schema" %} -{% swagger-description %} -Makes the selected schema active. Other schemas of the same type become inactive. Only suers with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +Makes the selected system schema active. Other schemas of the same entity type become inactive. Only users with the Standard Registry role are allowed to make this request. -{% swagger-parameter in="path" name="schemaID" type="String" required="true" %} -schema ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-parameter in="body" required="true" %} -Object that contains Policy Version -{% endswagger-parameter %} +**Permission:** `Permissions.SCHEMAS_SYSTEM_SCHEMA_REVIEW` -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/Schema' -} -``` -{% endswagger-response %} +--- -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -Schema is not system. -``` -{% endswagger-response %} +### Path Parameters -{% swagger-response status="404: Not Found" description="Not Found" %} +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `schemaId` | string | Yes | The schema ID (MongoDB ObjectId, e.g. `63e3e5e8a01b3c001234abcd`) | +--- -``` -Schema not found. -``` -{% endswagger-response %} +## Response -{% swagger-response status="422: Unprocessable Entity" description="Unprocessable Entity" %} +### Success Response +**Status:** `200 OK` -``` -Schema is active. -``` -{% endswagger-response %} +No response body. -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} -``` -{% endswagger-response %} -{% endswagger %} +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Schema is not a system schema | +| `404 Not Found` | Schema not found | +| `422 Unprocessable Entity` | Schema is already active | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/system-schemas-apis/returns-schema-by-type.md b/docs/system-schemas-apis/returns-schema-by-type.md index 95b11a8cc5..52b1292dbf 100644 --- a/docs/system-schemas-apis/returns-schema-by-type.md +++ b/docs/system-schemas-apis/returns-schema-by-type.md @@ -1,51 +1,51 @@ -# Returns Schema by Type +# Returns Schema by Schema Type -### FINDING SCHEMA USING JSON DOCUMENT +**`GET /schemas/type/{schemaType}`** -{% swagger method="get" path="" baseUrl="/schemas/type/{type}" summary="Returns Schema by Type" %} -{% swagger-description %} -Finds the schema using the json document type. -{% endswagger-description %} +Returns the schema matching the specified JSON document schema type string. -{% swagger-parameter in="path" name="type" type="String" %} -JSON type -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Schema' -} -``` -{% endswagger-response %} +--- -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `schemaType` | string | Yes | The schema type identifier (e.g. `#StandardRegistry`) | + +--- + +## Response -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "id": "63e3e5e8a01b3c001234abcd", + "name": "Standard Registry Schema", + "type": "#StandardRegistry", + "entity": "STANDARD_REGISTRY", + "status": "PUBLISHED", + "system": true, + "active": true, + "document": { + "$id": "#StandardRegistry", + "$schema": "http://json-schema.org/draft-07/schema", + "type": "object", + "properties": {} + } } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/system-schemas-apis/returns-schema-by-username.md b/docs/system-schemas-apis/returns-schema-by-username.md index 1fb5860b89..5573ce10aa 100644 --- a/docs/system-schemas-apis/returns-schema-by-username.md +++ b/docs/system-schemas-apis/returns-schema-by-username.md @@ -1,66 +1,58 @@ # Returns Schema by Username -### RETURNS ALL SYSTEM SCHEMAS BY USERNAME - -{% swagger method="get" path="" baseUrl="/schemas/system/{username}" summary="Returns all System Schemas by Username" %} -{% swagger-description %} -Return all system schemas by username. Only user with the Standard Registry are allowed to make the request. -{% endswagger-description %} - -{% swagger-parameter in="path" name="username" type="String" required="true" %} -Username -{% endswagger-parameter %} - -{% swagger-parameter in="query" name="pageIndex" type="Integer" required="false" %} -The number of pages to skip before starting to collect the result set. -{% endswagger-parameter %} - -{% swagger-parameter in="query" name="pageSize" type="Integer" required="false" %} -The number of items to return. -{% endswagger-parameter %} - -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - headers: - x-total-count: - schema: - type: integer - description: Total number of items in the collection. - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/Schema' -} -``` -{% endswagger-response %} +**`GET /schemas/system/{username}`** -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +Returns a paginated list of all system schemas for the specified user. Only users with the Standard Registry role are allowed to make this request. -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} - -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.SCHEMAS_SYSTEM_SCHEMA_READ` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `username` | string | Yes | Username of the schema owner | + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `pageIndex` | number | No | 0 | Zero-based page index | +| `pageSize` | number | No | 25 | Items per page | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +The response includes an `X-Total-Count` header with the total number of matching records. + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "name": "Example System Schema", + "entity": "STANDARD_REGISTRY", + "status": "PUBLISHED", + "system": true, + "active": true, + "owner": "example_user" + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/system-schemas-apis/schema-type.md b/docs/system-schemas-apis/schema-type.md index 8f36d4a739..ed1a5f11e2 100644 --- a/docs/system-schemas-apis/schema-type.md +++ b/docs/system-schemas-apis/schema-type.md @@ -1,59 +1,61 @@ -# Schema Type +# Returns Schema by Entity Type -### FINDS THE SCHEMA USING SCHEMA TYPE +**`GET /schemas/system/entity/{schemaEntity}`** -{% swagger method="get" path="" baseUrl="/schemas/system/entity/{schemaEntity}" summary="Returns Schema by Schema Type" %} -{% swagger-description %} -Finds the schema using Schema Type. -{% endswagger-description %} +Returns the active system schema for the specified entity type. -{% swagger-parameter in="path" name="schemaEntity" type="String" required="true" %} -Schema Type -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Schema' -} -``` -{% endswagger-response %} +--- -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +### Path Parameters -{% swagger-response status="404: Not Found" description="Not Found" %} +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `schemaEntity` | string | Yes | Entity type of the schema | +Valid `schemaEntity` values: -``` -Schema not found. -``` -{% endswagger-response %} +| Value | Description | +|-------|-------------| +| `STANDARD_REGISTRY` | Standard Registry entity schema | +| `USER` | User entity schema | +| `POLICY` | Policy entity schema | +| `MINT_TOKEN` | Fungible token mint schema | +| `WIPE_TOKEN` | Token wipe schema | +| `MINT_NFTOKEN` | Non-fungible token mint schema | + +--- + +## Response -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "id": "63e3e5e8a01b3c001234abcd", + "name": "Standard Registry Schema", + "entity": "STANDARD_REGISTRY", + "status": "PUBLISHED", + "system": true, + "active": true, + "document": { + "$id": "#StandardRegistry", + "$schema": "http://json-schema.org/draft-07/schema", + "type": "object", + "properties": {} + } } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `404 Not Found` | Schema not found for the given entity type | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/system-schemas-apis/updates-the-schema.md b/docs/system-schemas-apis/updates-the-schema.md index 51ddb31a57..26411d0b5a 100644 --- a/docs/system-schemas-apis/updates-the-schema.md +++ b/docs/system-schemas-apis/updates-the-schema.md @@ -1,65 +1,71 @@ # Updates the Schema -### UPDATES THE SCHEMA +**`PUT /schemas/system/{schemaId}`** -{% swagger method="put" path="" baseUrl="/schemas/system/{schemaId}" summary="Updates the Schema" %} -{% swagger-description %} -Updates the system Schema with the provided Schema ID. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +Updates the system schema with the specified schema ID. Only users with the Standard Registry role are allowed to make this request. -{% swagger-parameter in="path" name="schemaId" type="String" required="true" %} -SchemaID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-parameter in="path" required="true" %} -Object that contains valid Schema -{% endswagger-parameter %} +**Permission:** `Permissions.SCHEMAS_SYSTEM_SCHEMA_UPDATE` -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/Schema' -} -``` -{% endswagger-response %} +--- -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `schemaId` | string | Yes | The schema ID (MongoDB ObjectId) | + +### Request Body -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +```json { - // Response + "name": "Updated Schema Name", + "description": "Updated description", + "document": { + "$id": "#Example", + "$schema": "http://json-schema.org/draft-07/schema", + "type": "object", + "properties": {} + } } ``` -{% endswagger-response %} -{% swagger-response status="422: Unprocessable Entity" description="Unprocessable Entity" %} +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | No | Updated schema name | +| `description` | string | No | Updated schema description | +| `document` | object | No | Updated JSON Schema definition | +--- -``` -Schema is active. -``` -{% endswagger-response %} +## Response -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} +### Success Response + +**Status:** `200 OK` + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "name": "Updated Schema Name", + "entity": "STANDARD_REGISTRY", + "status": "DRAFT", + "system": true, + "active": false, + "owner": "example_user" + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | Schema is active and cannot be modified | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/task-apis/README.md b/docs/task-apis/README.md new file mode 100644 index 0000000000..894512d44f --- /dev/null +++ b/docs/task-apis/README.md @@ -0,0 +1,21 @@ +# Task APIs + +**Base URL:** `/api/v1/tasks` + +These endpoints allow callers to poll the status of asynchronous operations initiated by any Guardian `/push` endpoint, returning the task state, progress, and result or error detail. + +**Authentication:** All endpoints require a valid JWT Bearer token (`Authorization: Bearer `). Obtain a token via `POST /accounts/login`. + +--- + +## Endpoints + +| Method | Endpoint | Description | Auth Required | +|--------|----------|-------------|---------------| +| GET | `/tasks/{taskId}` | Return the current status and result of an asynchronous task | Yes | + +--- + +## Endpoint Details + +* [Returning Task Statuses](returning-task-statuses.md) — `GET /tasks/{taskId}` diff --git a/docs/task-apis/returning-task-statuses.md b/docs/task-apis/returning-task-statuses.md index e7b3f9f755..eb1f295c25 100644 --- a/docs/task-apis/returning-task-statuses.md +++ b/docs/task-apis/returning-task-statuses.md @@ -1,49 +1,57 @@ # Returning Task Statuses -{% swagger method="get" path="" baseUrl="/tasks/{taskId}" summary="Returns task statuses." %} -{% swagger-description %} -Returns task statuses by Id. -{% endswagger-description %} +**`GET /tasks/{taskId}`** -{% swagger-parameter in="path" name="taskId" type="String" required="true" %} -Task ID -{% endswagger-parameter %} +Returns the current status and result of an asynchronous task by its ID. -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/TaskStatus' -} -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `taskId` | string (UUID) | Yes | The unique identifier of the task | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "taskId": "63e3e5e8a01b3c001234abcd", + "action": "Create policy", + "done": true, + "error": null, + "result": {}, + "steps": [ + { + "time": "2024-06-01T12:34:56.789Z", + "message": "Policy created" + } + ] } ``` -{% endswagger-response %} -{% endswagger %} + +| Field | Type | Description | +|-------|------|-------------| +| `taskId` | string | The task identifier | +| `action` | string | Description of the task action | +| `done` | boolean | Whether the task has completed | +| `error` | object \| null | Error details if the task failed | +| `result` | object \| null | Task result payload when done | +| `steps` | array | Progress steps completed so far | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/token-apis/README.md b/docs/token-apis/README.md new file mode 100644 index 0000000000..dea0bc81cc --- /dev/null +++ b/docs/token-apis/README.md @@ -0,0 +1,39 @@ +# Token APIs + +The Token APIs provide endpoints for managing Hedera tokens, including creation, association, KYC management, and freeze controls. + +**Base URL:** `/api/v1/tokens` + +--- + +## Endpoints + +| Method | Endpoint | Description | Auth Required | +|--------|----------|-------------|---------------| +| **`GET`** | `/tokens/` | Returns list of all tokens | Yes | +| **`GET`** | `/tokens/{tokenId}` | Returns a single token by ID | Yes | +| **`POST`** | `/tokens/` | Creates a new token | Yes | +| **`PUT`** | `/tokens/` | Updates an existing token | Yes | +| **`PUT`** | `/tokens/{tokenId}/associate` | Associates the user with the token | Yes | +| **`PUT`** | `/tokens/{tokenId}/dissociate` | Disassociates the user from the token | Yes | +| **`PUT`** | `/tokens/{tokenId}/{username}/grant-kyc` | Sets the KYC flag for the user | Yes | +| **`PUT`** | `/tokens/{tokenId}/{username}/revoke-kyc` | Unsets the KYC flag for the user | Yes | +| **`PUT`** | `/tokens/{tokenId}/{username}/freeze` | Freezes token transfers for the user | Yes | +| **`PUT`** | `/tokens/{tokenId}/{username}/unfreeze` | Unfreezes token transfers for the user | Yes | +| **`GET`** | `/tokens/{tokenId}/{username}/info` | Returns token status info for the user | Yes | + +--- + +## Endpoint Details + +* [Token Listing](token-listing.md) +* [Return Token by ID](returns-token-by-id.md) +* [Creation of a Token](token-listing-1.md) +* [Updating a Token](updating-a-token.md) +* [Associates the User with Token](associates-the-user-with-token.md) +* [Disassociates the User from Token](disassociates-the-user-with-token.md) +* [Grants KYC for the User](grants-kyc-for-the-user.md) +* [Revoke KYC of the User](revoke-kyc-of-the-user.md) +* [Freeze Tokens of a User](freeze-tokens-of-a-user.md) +* [Unfreeze Tokens of a User](unfreeze-tokens-of-a-user.md) +* [User Info for Selected Token](user-info-for-selected-token.md) diff --git a/docs/token-apis/associates-the-user-with-token.md b/docs/token-apis/associates-the-user-with-token.md index 8b9c0d46a2..5cb805b14b 100644 --- a/docs/token-apis/associates-the-user-with-token.md +++ b/docs/token-apis/associates-the-user-with-token.md @@ -1,48 +1,46 @@ -# Associates the user with token +# Associates the User with Token -### ASSOCIATES USER WITH TOKEN +**`PUT /tokens/{tokenId}/associate`** -{% swagger method="put" path="" baseUrl="/tokens/{tokenId}/associate" summary="Associates the user with the provided Hedera token" %} -{% swagger-description %} -Associates the user with the provided Hedera token. Only users with the Installer role are allowed to make the request -{% endswagger-description %} +Associates the authenticated user with the specified Hedera token. -{% swagger-parameter in="path" name="tokenID" type="String" required="true" %} -Token ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +**Permission:** `Permissions.TOKENS_TOKEN_EXECUTE` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `tokenId` | string | Yes | The Hedera token ID (e.g. `0.0.5000001`) | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "id": "63e3e5e8a01b3c001234abcd", + "tokenId": "0.0.5000001", + "associated": true, + "balance": "0", + "frozen": false, + "kyc": false } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/token-apis/disassociates-the-user-with-token.md b/docs/token-apis/disassociates-the-user-with-token.md index 3d6ead3fc2..41f968c06e 100644 --- a/docs/token-apis/disassociates-the-user-with-token.md +++ b/docs/token-apis/disassociates-the-user-with-token.md @@ -1,48 +1,46 @@ -# Disassociates the user with token +# Disassociates the User from Token -### DISASSOCIATES USER WITH TOKEN +**`PUT /tokens/{tokenId}/dissociate`** -{% swagger method="put" path="" baseUrl="/tokens/{tokenId}/dissociate" summary="Disassociate the user with the provided Hedera token" %} -{% swagger-description %} -Disassociates the user with the provided Hedera token. Only users with the Installer role are allowed to make the request. -{% endswagger-description %} +Disassociates the authenticated user from the specified Hedera token. -{% swagger-parameter in="path" name="tokenID" type="String" required="true" %} -Token ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +**Permission:** `Permissions.TOKENS_TOKEN_EXECUTE` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `tokenId` | string | Yes | The Hedera token ID (e.g. `0.0.5000001`) | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "id": "63e3e5e8a01b3c001234abcd", + "tokenId": "0.0.5000001", + "associated": false, + "balance": "0", + "frozen": false, + "kyc": false } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/token-apis/freeze-tokens-of-a-user.md b/docs/token-apis/freeze-tokens-of-a-user.md index 8ff962b697..16cea6c5ea 100644 --- a/docs/token-apis/freeze-tokens-of-a-user.md +++ b/docs/token-apis/freeze-tokens-of-a-user.md @@ -1,66 +1,48 @@ -# Freeze Tokens of a user +# Freeze Tokens of a User -### FREEZE TRANSFER OF TOKENS OF A USER +**`PUT /tokens/{tokenId}/{username}/freeze`** -{% swagger method="put" path="" baseUrl="/tokens/{tokenId}/{username}/freeze" summary="Freeze transfers of the specified token for the user" %} -{% swagger-description %} -Freezes transfers of the specified token for the user. Only users with the Standard Registry role are allowed to make the request -{% endswagger-description %} +Freezes transfers of the specified Hedera token for the given user. Only users with the Standard Registry role are allowed to make this request. -{% swagger-parameter in="path" name="tokenID" type="String" required="true" %} -Token ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-parameter in="path" name="username" type="String" required="true" %} -Username -{% endswagger-parameter %} +**Permission:** `Permissions.TOKENS_TOKEN_EXECUTE` -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/TokenInfo' -} -``` -{% endswagger-response %} +--- -{% swagger-response status="400: Bad Request" description="Bad Request" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +### Path Parameters -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `tokenId` | string | Yes | The Hedera token ID (e.g. `0.0.5000001`) | +| `username` | string | Yes | The username of the target user | + +--- + +## Response -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "id": "63e3e5e8a01b3c001234abcd", + "tokenId": "0.0.5000001", + "associated": true, + "balance": "0", + "frozen": true, + "kyc": true } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `400 Bad Request` | Invalid token or username | +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/token-apis/grants-kyc-for-the-user.md b/docs/token-apis/grants-kyc-for-the-user.md index 4093b0b6a5..cb6a9d76c0 100644 --- a/docs/token-apis/grants-kyc-for-the-user.md +++ b/docs/token-apis/grants-kyc-for-the-user.md @@ -1,66 +1,48 @@ -# Grants KYC for the user +# Grants KYC for the User -### GRANTS KYC FLAG FOR THE USER +**`PUT /tokens/{tokenId}/{username}/grant-kyc`** -{% swagger method="put" path="" baseUrl="/tokens/{tokenId}/{username}/grant-kyc" summary="Sets the KYC flag for the user." %} -{% swagger-description %} -Sets the KYC flag for the user. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +Sets the KYC flag for the specified user on the given Hedera token. Only users with the Standard Registry role are allowed to make this request. -{% swagger-parameter in="path" name="tokenID" type="String" required="true" %} -Token ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-parameter in="path" name="username" type="String" required="true" %} -Username -{% endswagger-parameter %} +**Permission:** `Permissions.TOKENS_TOKEN_EXECUTE` -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/TokenInfo' -} -``` -{% endswagger-response %} +--- -{% swagger-response status="400: Bad Request" description="Bad Request" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +### Path Parameters -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `tokenId` | string | Yes | The Hedera token ID (e.g. `0.0.5000001`) | +| `username` | string | Yes | The username of the target user | + +--- + +## Response -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "id": "63e3e5e8a01b3c001234abcd", + "tokenId": "0.0.5000001", + "associated": true, + "balance": "0", + "frozen": false, + "kyc": true } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `400 Bad Request` | Invalid token or username | +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/token-apis/returns-token-by-id.md b/docs/token-apis/returns-token-by-id.md new file mode 100644 index 0000000000..1c2fc5454d --- /dev/null +++ b/docs/token-apis/returns-token-by-id.md @@ -0,0 +1,62 @@ +# Return Token by ID + +**`GET /tokens/{tokenId}`** + +Returns a single token by its ID, with associated policy information. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.TOKENS_TOKEN_READ` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `tokenId` | string | Yes | The Hedera token ID (e.g. `0.0.5000001`) | + +### Query Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `policyId` | string | No | Filter by policy ID | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "tokenId": "0.0.5000001", + "tokenName": "Example Token", + "tokenSymbol": "ET", + "tokenType": "fungible", + "decimals": 2, + "initialSupply": 0, + "enableAdmin": true, + "changeSupply": true, + "enableFreeze": true, + "enableKYC": true, + "enableWipe": true, + "policies": ["Example Policy (1.0.0)"], + "policyIds": ["63e3e5e8a01b3c001234abce"] +} +``` + +Returns `null` if no token is found with the given ID. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/token-apis/revoke-kyc-of-the-user.md b/docs/token-apis/revoke-kyc-of-the-user.md index d4b1d10685..2939610cde 100644 --- a/docs/token-apis/revoke-kyc-of-the-user.md +++ b/docs/token-apis/revoke-kyc-of-the-user.md @@ -1,66 +1,48 @@ -# Revoke KYC of the user +# Revoke KYC of the User -### UNSETS KYC FLAG FOR THE USER +**`PUT /tokens/{tokenId}/{username}/revoke-kyc`** -{% swagger method="put" path="" baseUrl="/tokens/{tokenId}/{username}/revoke-kyc" summary="Unsets the KYC flag for the user." %} -{% swagger-description %} -Unsets the KYC flag for the user. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +Unsets (revokes) the KYC flag for the specified user on the given Hedera token. Only users with the Standard Registry role are allowed to make this request. -{% swagger-parameter in="path" name="tokenID" type="String" required="true" %} -Token ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-parameter in="path" name="username" type="String" required="true" %} -Username -{% endswagger-parameter %} +**Permission:** `Permissions.TOKENS_TOKEN_EXECUTE` -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/TokenInfo' -} -``` -{% endswagger-response %} +--- -{% swagger-response status="400: Bad Request" description="Bad Request" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +### Path Parameters -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `tokenId` | string | Yes | The Hedera token ID (e.g. `0.0.5000001`) | +| `username` | string | Yes | The username of the target user | + +--- + +## Response -{% swagger-response status="500: Internal Server Error" description="" %} -```javascript +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "id": "63e3e5e8a01b3c001234abcd", + "tokenId": "0.0.5000001", + "associated": true, + "balance": "0", + "frozen": false, + "kyc": false } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `400 Bad Request` | Invalid token or username | +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/token-apis/token-listing-1.md b/docs/token-apis/token-listing-1.md index e81fb61461..4ad0412fc8 100644 --- a/docs/token-apis/token-listing-1.md +++ b/docs/token-apis/token-listing-1.md @@ -1,72 +1,78 @@ -# Creation of Token +# Creation of a Token -### CREATION OF A TOKEN +**`POST /tokens/`** -{% swagger method="post" path="" baseUrl="/tokens" summary="Creates a new token" %} -{% swagger-description %} -Creates a new token. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +Creates a new Hedera token. Only users with the Standard Registry role are allowed to make this request. -{% swagger-parameter in="body" required="true" %} -Object that contains token information -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="201: Created" description="Created" %} -```javascript -{ - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/TokenInfo' -} -``` -{% endswagger-response %} +**Permission:** `Permissions.TOKENS_TOKEN_CREATE` -{% swagger-response status="400: Bad Request" description="Bad Request" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} -``` -{% endswagger-response %} +--- -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request + +### Request Body -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript +```json { - // Response + "tokenName": "Example Token", + "tokenSymbol": "ET", + "tokenType": "fungible", + "decimals": 2, + "initialSupply": 0, + "enableAdmin": true, + "changeSupply": true, + "enableFreeze": true, + "enableKYC": true, + "enableWipe": true } ``` -{% endswagger-response %} -{% swagger-response status="422: Unprocessable Entity" description="Unprocessable Entity" %} +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `tokenName` | string | Yes | Name of the token | +| `tokenSymbol` | string | Yes | Symbol of the token | +| `tokenType` | string | Yes | Token type: `fungible` or `non-fungible` | +| `decimals` | number | No | Number of decimal places (fungible only) | +| `initialSupply` | number | No | Initial supply amount | +| `enableAdmin` | boolean | No | Whether admin key is enabled | +| `changeSupply` | boolean | No | Whether supply can be changed | +| `enableFreeze` | boolean | No | Whether freeze key is enabled | +| `enableKYC` | boolean | No | Whether KYC key is enabled | +| `enableWipe` | boolean | No | Whether wipe key is enabled | +--- -``` -User not registered -``` -{% endswagger-response %} +## Response -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} +### Success Response + +**Status:** `201 Created` + +Returns an updated array of all tokens. + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "tokenId": "0.0.5000001", + "tokenName": "Example Token", + "tokenSymbol": "ET", + "tokenType": "fungible", + "decimals": 2, + "initialSupply": 0, + "policies": [], + "policyIds": [] + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | User not registered with Hedera | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/token-apis/token-listing.md b/docs/token-apis/token-listing.md index 82e8539eb1..d5b6363504 100644 --- a/docs/token-apis/token-listing.md +++ b/docs/token-apis/token-listing.md @@ -1,55 +1,65 @@ # Token Listing -### DISPLAYS ALL TOKENS - -{% swagger method="get" path="" baseUrl="/tokens" summary="Return a list of tokens" %} -{% swagger-description %} -Returns all tokens. For the Standard Registry role it returns only the list of tokens, for other users it also returns token balances as well as the KYC, Freeze, and Association statuses. Not allowed for the Auditor role. -{% endswagger-description %} - -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - application/json: - schema: - type: array - items: - allOf: - - $ref: '#/components/schemas/TokenInfo' - - type: object - properties: - policies: - type: array - items: - type: string -} -``` -{% endswagger-response %} +**`GET /tokens/`** -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +Returns a list of all tokens. For the Standard Registry role it returns only the token list; for other users it also returns token balances and KYC, Freeze, and Association statuses. -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} - -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.TOKENS_TOKEN_READ` + +--- + +## Request + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `pageIndex` | number | No | 0 | Zero-based page index | +| `pageSize` | number | No | 20 | Items per page | +| `policyId` | string | No | — | Filter tokens by policy ID | +| `status` | string | No | — | Filter by association status: `Associated` or `All` | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +The response includes an `X-Total-Count` header with the total number of matching records. + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "tokenId": "0.0.5000001", + "tokenName": "Example Token", + "tokenSymbol": "ET", + "tokenType": "fungible", + "decimals": 2, + "initialSupply": 0, + "enableAdmin": true, + "changeSupply": true, + "enableFreeze": true, + "enableKYC": true, + "enableWipe": true, + "policies": ["Example Policy (1.0.0)"], + "policyIds": ["63e3e5e8a01b3c001234abce"], + "associated": true, + "balance": "100", + "frozen": false, + "kyc": true + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/token-apis/unfreeze-tokens-of-a-user.md b/docs/token-apis/unfreeze-tokens-of-a-user.md index 7e1040f71c..2ec14e8de0 100644 --- a/docs/token-apis/unfreeze-tokens-of-a-user.md +++ b/docs/token-apis/unfreeze-tokens-of-a-user.md @@ -1,66 +1,48 @@ -# UnFreeze Tokens of a user +# Unfreeze Tokens of a User -### UNFREEZE TRANSFER OF TOKENS OF A USER +**`PUT /tokens/{tokenId}/{username}/unfreeze`** -{% swagger method="put" path="" baseUrl="/tokens/{tokenId}/{username}/unfreeze" summary="Unfreezes transfers of the specified token for the user" %} -{% swagger-description %} -Unfreezes transfers of the specified token for the user. Only users with the Standard Registry role are allowed to make the request -{% endswagger-description %} +Unfreezes transfers of the specified Hedera token for the given user. Only users with the Standard Registry role are allowed to make this request. -{% swagger-parameter in="path" name="tokenID" type="String" required="true" %} -Token ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-parameter in="path" name="username" type="String" required="true" %} -Username -{% endswagger-parameter %} +**Permission:** `Permissions.TOKENS_TOKEN_EXECUTE` -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/TokenInfo' -} -``` -{% endswagger-response %} +--- -{% swagger-response status="400: Bad Request" description="Bad Request" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +### Path Parameters -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `tokenId` | string | Yes | The Hedera token ID (e.g. `0.0.5000001`) | +| `username` | string | Yes | The username of the target user | + +--- + +## Response -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "id": "63e3e5e8a01b3c001234abcd", + "tokenId": "0.0.5000001", + "associated": true, + "balance": "0", + "frozen": false, + "kyc": true } ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `400 Bad Request` | Invalid token or username | +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/token-apis/updating-a-token.md b/docs/token-apis/updating-a-token.md new file mode 100644 index 0000000000..395fb889db --- /dev/null +++ b/docs/token-apis/updating-a-token.md @@ -0,0 +1,70 @@ +# Updating a Token + +**`PUT /tokens/`** + +Updates an existing token's configuration. Only users with the Standard Registry role are allowed to make this request. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.TOKENS_TOKEN_UPDATE` + +--- + +## Request + +### Request Body + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "tokenId": "0.0.5000001", + "tokenName": "Updated Token Name", + "tokenSymbol": "ET", + "enableAdmin": true, + "changeSupply": true, + "enableFreeze": true, + "enableKYC": true, + "enableWipe": true +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `id` | string | Yes | Internal database ID of the token | +| `tokenId` | string | Yes | Hedera token ID | +| `tokenName` | string | No | Updated token name | +| `tokenSymbol` | string | No | Updated token symbol | +| `enableAdmin` | boolean | No | Whether admin key is enabled | +| `changeSupply` | boolean | No | Whether supply can be changed | +| `enableFreeze` | boolean | No | Whether freeze key is enabled | +| `enableKYC` | boolean | No | Whether KYC key is enabled | +| `enableWipe` | boolean | No | Whether wipe key is enabled | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +Returns an updated array of all tokens. + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "tokenId": "0.0.5000001", + "tokenName": "Updated Token Name", + "tokenSymbol": "ET" + } +] +``` + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/token-apis/user-info-for-selected-token.md b/docs/token-apis/user-info-for-selected-token.md index 7bc9b2a616..e7bbe62340 100644 --- a/docs/token-apis/user-info-for-selected-token.md +++ b/docs/token-apis/user-info-for-selected-token.md @@ -1,66 +1,57 @@ -# User Info for selected token +# User Info for Selected Token -### DISPLAYS USER INFORMATION FOR SELECTED TOKEN +**`GET /tokens/{tokenId}/{username}/info`** -{% swagger method="get" path="" baseUrl="/tokens/{tokenId}/{username}/info" summary="Returns User information" %} -{% swagger-description %} -Returns user information for the selected token. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +Returns the token status information for the specified user on the given Hedera token. Only users with the Standard Registry role are allowed to make this request. -{% swagger-parameter in="path" name="tokenID" type="String" required="true" %} -Token ID -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-parameter in="path" name="username" required="true" %} -Username -{% endswagger-parameter %} +**Permission:** `Permissions.TOKENS_TOKEN_READ` -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/TokenInfo' -} -``` -{% endswagger-response %} +--- -{% swagger-response status="400: Bad Request" description="Bad Request" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +### Path Parameters -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `tokenId` | string | Yes | The Hedera token ID (e.g. `0.0.5000001`) | +| `username` | string | Yes | The username of the target user | + +--- -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +## Response + +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "id": "63e3e5e8a01b3c001234abcd", + "tokenId": "0.0.5000001", + "associated": true, + "balance": "100", + "frozen": false, + "kyc": true } ``` -{% endswagger-response %} -{% endswagger %} + +| Field | Type | Description | +|-------|------|-------------| +| `id` | string | Internal database ID | +| `tokenId` | string | Hedera token ID | +| `associated` | boolean | Whether the user is associated with the token | +| `balance` | string | User's token balance | +| `frozen` | boolean | Whether the user's token transfers are frozen | +| `kyc` | boolean | Whether the user has passed KYC | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `400 Bad Request` | Invalid token or username | +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/token-related-apis-for-asynchronous-execution/README.md b/docs/token-related-apis-for-asynchronous-execution/README.md new file mode 100644 index 0000000000..94adf2e786 --- /dev/null +++ b/docs/token-related-apis-for-asynchronous-execution/README.md @@ -0,0 +1,37 @@ +# Token APIs — Asynchronous Execution + +The Token async APIs provide asynchronous endpoints for token creation, update, deletion, association, and KYC/freeze management. All endpoints return `202 Accepted` with a `taskId`. Poll `GET /tasks/{taskId}` to retrieve the result. + +**Base URL:** `/api/v1/tokens/push` + +--- + +## Endpoints + +| Method | Endpoint | Description | Auth Required | +|--------|----------|-------------|---------------| +| **`POST`** | `/tokens/push` | Creates a new token (async) | Yes | +| **`PUT`** | `/tokens/push` | Updates an existing token (async) | Yes | +| **`DELETE`** | `/tokens/push/{tokenId}` | Deletes a token (async) | Yes | +| **`POST`** | `/tokens/push/delete-multiple` | Deletes multiple tokens (async) | Yes | +| **`PUT`** | `/tokens/push/{tokenId}/associate` | Associates the user with the token (async) | Yes | +| **`PUT`** | `/tokens/push/{tokenId}/dissociate` | Disassociates the user from the token (async) | Yes | +| **`PUT`** | `/tokens/push/{tokenId}/{username}/grant-kyc` | Sets the KYC flag for the user (async) | Yes | +| **`PUT`** | `/tokens/push/{tokenId}/{username}/revoke-kyc` | Unsets the KYC flag for the user (async) | Yes | +| **`PUT`** | `/tokens/push/{tokenId}/{username}/freeze` | Freezes token transfers for the user (async) | Yes | +| **`PUT`** | `/tokens/push/{tokenId}/{username}/unfreeze` | Unfreezes token transfers for the user (async) | Yes | + +--- + +## Endpoint Details + +* [Token Creation](token-creation.md) +* [Updating a Token](updating-a-token.md) +* [Deleting a Token](deleting-a-token.md) +* [Deleting Multiple Tokens](deleting-multiple-tokens.md) +* [Associating User with the Hedera Token](associating-user-with-the-hedera-token.md) +* [Disassociating User from the Hedera Token](disassociating-user-with-the-hedera-token.md) +* [Setting KYC for the User](setting-kyc-for-the-user.md) +* [Unsetting KYC for the User](unsetting-kyc-for-the-user.md) +* [Freezing Tokens of a User](freezing-tokens-of-a-user.md) +* [Unfreezing Tokens of a User](unfreezing-tokens-of-a-user.md) diff --git a/docs/token-related-apis-for-asynchronous-execution/associating-user-with-the-hedera-token.md b/docs/token-related-apis-for-asynchronous-execution/associating-user-with-the-hedera-token.md index dc8b8113f7..2dc647b9fd 100644 --- a/docs/token-related-apis-for-asynchronous-execution/associating-user-with-the-hedera-token.md +++ b/docs/token-related-apis-for-asynchronous-execution/associating-user-with-the-hedera-token.md @@ -1,57 +1,45 @@ -# Associating User with the Hedera Token +# Associating User with the Hedera Token (Async) -{% swagger method="put" path="" baseUrl="/tokens/push/{tokenId}/associate" summary="Associates the user with the provided Hedera token." %} -{% swagger-description %} -Associates the user with the provided Hedera token. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`PUT /tokens/push/{tokenId}/associate`** -{% swagger-parameter in="path" name="tokenId" type="String" required="true" %} -Token ID -{% endswagger-parameter %} +Associates the authenticated user with the specified Hedera token asynchronously. -{% swagger-response status="202: Accepted" description="Accepted" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Task' -} -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthroized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +**Permission:** `Permissions.TOKENS_TOKEN_EXECUTE` -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- -{% swagger-response status="422: Unprocessable Entity" description="Unprocessable Entity" %} +## Request +### Path Parameters -``` -User not registered -``` -{% endswagger-response %} +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `tokenId` | string | Yes | The Hedera token ID (e.g. `0.0.5000001`) | + +--- + +## Response + +### Success Response -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +**Status:** `202 Accepted` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Associate token" } ``` -{% endswagger-response %} -{% endswagger %} + +Poll `GET /tasks/{taskId}` to retrieve the result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | User not registered with Hedera | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/token-related-apis-for-asynchronous-execution/deleting-a-token.md b/docs/token-related-apis-for-asynchronous-execution/deleting-a-token.md new file mode 100644 index 0000000000..670e181bff --- /dev/null +++ b/docs/token-related-apis-for-asynchronous-execution/deleting-a-token.md @@ -0,0 +1,44 @@ +# Deleting a Token (Async) + +**`DELETE /tokens/push/{tokenId}`** + +Deletes a Hedera token asynchronously. Only users with the Standard Registry role are allowed to make this request. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.TOKENS_TOKEN_DELETE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `tokenId` | string | Yes | The Hedera token ID (e.g. `0.0.5000001`) | + +--- + +## Response + +### Success Response + +**Status:** `202 Accepted` + +```json +{ + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Delete token" +} +``` + +Poll `GET /tasks/{taskId}` to retrieve the result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/token-related-apis-for-asynchronous-execution/deleting-multiple-tokens.md b/docs/token-related-apis-for-asynchronous-execution/deleting-multiple-tokens.md new file mode 100644 index 0000000000..ed51b1f1bf --- /dev/null +++ b/docs/token-related-apis-for-asynchronous-execution/deleting-multiple-tokens.md @@ -0,0 +1,50 @@ +# Deleting Multiple Tokens (Async) + +**`POST /tokens/push/delete-multiple`** + +Deletes multiple Hedera tokens asynchronously. Only users with the Standard Registry role are allowed to make this request. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.TOKENS_TOKEN_DELETE` + +--- + +## Request + +### Request Body + +```json +{ + "tokenIds": ["0.0.5000001", "0.0.5000002"] +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `tokenIds` | string[] | Yes | Array of Hedera token IDs to delete | + +--- + +## Response + +### Success Response + +**Status:** `202 Accepted` + +```json +{ + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Delete multiple tokens" +} +``` + +Poll `GET /tasks/{taskId}` to retrieve the result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/token-related-apis-for-asynchronous-execution/disassociating-user-with-the-hedera-token.md b/docs/token-related-apis-for-asynchronous-execution/disassociating-user-with-the-hedera-token.md index cd44537728..17a130a55f 100644 --- a/docs/token-related-apis-for-asynchronous-execution/disassociating-user-with-the-hedera-token.md +++ b/docs/token-related-apis-for-asynchronous-execution/disassociating-user-with-the-hedera-token.md @@ -1,58 +1,45 @@ -# Disassociating User with the Hedera Token +# Disassociating User from the Hedera Token (Async) -{% swagger method="put" path="" baseUrl="/tokens/push/{tokenId}/dissociate" summary="Disassociates the user with the provided Hedera token." %} -{% swagger-description %} -Disassociates the user with the provided Hedera token. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`PUT /tokens/push/{tokenId}/dissociate`** -{% swagger-parameter in="path" required="true" name="tokenId" type="String" %} -Token ID -{% endswagger-parameter %} +Disassociates the authenticated user from the specified Hedera token asynchronously. -{% swagger-response status="202: Accepted" description="Accepted" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Task' -} -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +**Permission:** `Permissions.TOKENS_TOKEN_EXECUTE` -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- -{% swagger-response status="422: Unprocessable Entity" description="Unprocessable Entity" %} +## Request +### Path Parameters -``` -User not registered -``` -{% endswagger-response %} +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `tokenId` | string | Yes | The Hedera token ID (e.g. `0.0.5000001`) | + +--- + +## Response -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +### Success Response + +**Status:** `202 Accepted` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Dissociate token" } ``` -{% endswagger-response %} -{% endswagger %} +Poll `GET /tasks/{taskId}` to retrieve the result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | User not registered with Hedera | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/token-related-apis-for-asynchronous-execution/freezing-tokens-of-a-user.md b/docs/token-related-apis-for-asynchronous-execution/freezing-tokens-of-a-user.md new file mode 100644 index 0000000000..93a8877643 --- /dev/null +++ b/docs/token-related-apis-for-asynchronous-execution/freezing-tokens-of-a-user.md @@ -0,0 +1,45 @@ +# Freezing Tokens of a User (Async) + +**`PUT /tokens/push/{tokenId}/{username}/freeze`** + +Freezes transfers of the specified Hedera token for the given user asynchronously. Only users with the Standard Registry role are allowed to make this request. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.TOKENS_TOKEN_EXECUTE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `tokenId` | string | Yes | The Hedera token ID (e.g. `0.0.5000001`) | +| `username` | string | Yes | The username of the target user | + +--- + +## Response + +### Success Response + +**Status:** `202 Accepted` + +```json +{ + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Freeze token" +} +``` + +Poll `GET /tasks/{taskId}` to retrieve the result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/token-related-apis-for-asynchronous-execution/setting-kyc-for-the-user.md b/docs/token-related-apis-for-asynchronous-execution/setting-kyc-for-the-user.md index 62cefc3bf5..603c671801 100644 --- a/docs/token-related-apis-for-asynchronous-execution/setting-kyc-for-the-user.md +++ b/docs/token-related-apis-for-asynchronous-execution/setting-kyc-for-the-user.md @@ -1,53 +1,45 @@ -# Setting KYC for the User +# Setting KYC for the User (Async) -{% swagger method="put" path="" baseUrl="/tokens/push/{tokenId}/{username}/grant-kyc" summary="Sets the KYC flag for the user." %} -{% swagger-description %} -Sets the KYC flag for the user. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`PUT /tokens/push/{tokenId}/{username}/grant-kyc`** -{% swagger-parameter in="path" name="tokenId" type="String" required="true" %} -Token ID -{% endswagger-parameter %} +Sets the KYC flag for the specified user on the given Hedera token asynchronously. Only users with the Standard Registry role are allowed to make this request. -{% swagger-parameter in="path" name="username" type="String" required="true" %} -Username -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Task' -} -``` -{% endswagger-response %} +**Permission:** `Permissions.TOKENS_TOKEN_EXECUTE` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `tokenId` | string | Yes | The Hedera token ID (e.g. `0.0.5000001`) | +| `username` | string | Yes | The username of the target user | + +--- + +## Response + +### Success Response + +**Status:** `202 Accepted` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Grant KYC" } ``` -{% endswagger-response %} -{% endswagger %} + +Poll `GET /tasks/{taskId}` to retrieve the result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/token-related-apis-for-asynchronous-execution/token-creation.md b/docs/token-related-apis-for-asynchronous-execution/token-creation.md index 4dd452c12e..27dafe5ed8 100644 --- a/docs/token-related-apis-for-asynchronous-execution/token-creation.md +++ b/docs/token-related-apis-for-asynchronous-execution/token-creation.md @@ -1,73 +1,69 @@ -# Token Creation +# Token Creation (Async) -{% swagger method="post" path="" baseUrl="/tokens/push" summary="Creates a new token" %} -{% swagger-description %} -Creates a new token. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`POST /tokens/push`** -{% swagger-parameter in="body" required="true" %} -Object that contains token information -{% endswagger-parameter %} +Creates a new Hedera token asynchronously. Only users with the Standard Registry role are allowed to make this request. -{% swagger-response status="202: Accepted" description="Accepted" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Task' -} -``` -{% endswagger-response %} - -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} - -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="403: Forbidden" description="" %} +**Permission:** `Permissions.TOKENS_TOKEN_CREATE` -{% endswagger-response %} +--- -{% swagger-response status="404: Not Found" description="Not Found" %} +## Request +### Request Body +```json +{ + "tokenName": "Example Token", + "tokenSymbol": "ET", + "tokenType": "fungible", + "decimals": 2, + "initialSupply": 0, + "enableAdmin": true, + "changeSupply": true, + "enableFreeze": true, + "enableKYC": true, + "enableWipe": true +} ``` -Token not found -``` -{% endswagger-response %} -{% swagger-response status="422: Unprocessable Entity" description="Unprocessable Entity" %} +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `tokenName` | string | Yes | Name of the token | +| `tokenSymbol` | string | Yes | Symbol of the token | +| `tokenType` | string | Yes | Token type: `fungible` or `non-fungible` | +| `decimals` | number | No | Number of decimal places (fungible only) | +| `initialSupply` | number | No | Initial supply amount | +| `enableAdmin` | boolean | No | Whether admin key is enabled | +| `changeSupply` | boolean | No | Whether supply can be changed | +| `enableFreeze` | boolean | No | Whether freeze key is enabled | +| `enableKYC` | boolean | No | Whether KYC key is enabled | +| `enableWipe` | boolean | No | Whether wipe key is enabled | +--- -``` -The field tokenId is required -``` +## Response -``` -User not registered -``` -{% endswagger-response %} +### Success Response + +**Status:** `202 Accepted` -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Create token" } ``` -{% endswagger-response %} -{% endswagger %} + +Poll `GET /tasks/{taskId}` to retrieve the result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `422 Unprocessable Entity` | User not registered with Hedera | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/token-related-apis-for-asynchronous-execution/unfreezing-tokens-of-a-user.md b/docs/token-related-apis-for-asynchronous-execution/unfreezing-tokens-of-a-user.md new file mode 100644 index 0000000000..d34a33d1b1 --- /dev/null +++ b/docs/token-related-apis-for-asynchronous-execution/unfreezing-tokens-of-a-user.md @@ -0,0 +1,45 @@ +# Unfreezing Tokens of a User (Async) + +**`PUT /tokens/push/{tokenId}/{username}/unfreeze`** + +Unfreezes transfers of the specified Hedera token for the given user asynchronously. Only users with the Standard Registry role are allowed to make this request. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.TOKENS_TOKEN_EXECUTE` + +--- + +## Request + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `tokenId` | string | Yes | The Hedera token ID (e.g. `0.0.5000001`) | +| `username` | string | Yes | The username of the target user | + +--- + +## Response + +### Success Response + +**Status:** `202 Accepted` + +```json +{ + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Unfreeze token" +} +``` + +Poll `GET /tasks/{taskId}` to retrieve the result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/token-related-apis-for-asynchronous-execution/unsetting-kyc-for-the-user.md b/docs/token-related-apis-for-asynchronous-execution/unsetting-kyc-for-the-user.md index 389d9ce275..eca3a1cdfc 100644 --- a/docs/token-related-apis-for-asynchronous-execution/unsetting-kyc-for-the-user.md +++ b/docs/token-related-apis-for-asynchronous-execution/unsetting-kyc-for-the-user.md @@ -1,53 +1,45 @@ -# Unsetting KYC for the User +# Unsetting KYC for the User (Async) -{% swagger method="put" path="" baseUrl="/tokens/push/{tokenId}/{username}/revoke-kyc" summary="Unsets the KYC flag for the user." %} -{% swagger-description %} -Unsets the KYC flag for the user. Only users with the Standard Registry role are allowed to make the request. -{% endswagger-description %} +**`PUT /tokens/push/{tokenId}/{username}/revoke-kyc`** -{% swagger-parameter in="path" name="tokenId" type="String" required="true" %} -TokenID -{% endswagger-parameter %} +Unsets (revokes) the KYC flag for the specified user on the given Hedera token asynchronously. Only users with the Standard Registry role are allowed to make this request. -{% swagger-parameter in="path" name="username" type="String" required="true" %} -Username -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="Successful Operation" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Task' -} -``` -{% endswagger-response %} +**Permission:** `Permissions.TOKENS_TOKEN_EXECUTE` -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="Forbidden" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `tokenId` | string | Yes | The Hedera token ID (e.g. `0.0.5000001`) | +| `username` | string | Yes | The username of the target user | + +--- + +## Response + +### Success Response + +**Status:** `202 Accepted` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Revoke KYC" } ``` -{% endswagger-response %} -{% endswagger %} + +Poll `GET /tasks/{taskId}` to retrieve the result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/token-related-apis-for-asynchronous-execution/updating-a-token.md b/docs/token-related-apis-for-asynchronous-execution/updating-a-token.md new file mode 100644 index 0000000000..ebc5b125a9 --- /dev/null +++ b/docs/token-related-apis-for-asynchronous-execution/updating-a-token.md @@ -0,0 +1,66 @@ +# Updating a Token (Async) + +**`PUT /tokens/push`** + +Updates an existing Hedera token asynchronously. Only users with the Standard Registry role are allowed to make this request. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.TOKENS_TOKEN_UPDATE` + +--- + +## Request + +### Request Body + +```json +{ + "id": "63e3e5e8a01b3c001234abcd", + "tokenId": "0.0.5000001", + "tokenName": "Updated Token Name", + "tokenSymbol": "ET", + "enableAdmin": true, + "changeSupply": true, + "enableFreeze": true, + "enableKYC": true, + "enableWipe": true +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `id` | string | Yes | Internal database ID of the token | +| `tokenId` | string | Yes | Hedera token ID | +| `tokenName` | string | No | Updated token name | +| `tokenSymbol` | string | No | Updated token symbol | +| `enableAdmin` | boolean | No | Whether admin key is enabled | +| `changeSupply` | boolean | No | Whether supply can be changed | +| `enableFreeze` | boolean | No | Whether freeze key is enabled | +| `enableKYC` | boolean | No | Whether KYC key is enabled | +| `enableWipe` | boolean | No | Whether wipe key is enabled | + +--- + +## Response + +### Success Response + +**Status:** `202 Accepted` + +```json +{ + "taskId": "63e3e5e8a01b3c001234abcd", + "expectation": "Update token" +} +``` + +Poll `GET /tasks/{taskId}` to retrieve the result. + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/trustchains-apis/README.md b/docs/trustchains-apis/README.md new file mode 100644 index 0000000000..4b2335c332 --- /dev/null +++ b/docs/trustchains-apis/README.md @@ -0,0 +1,23 @@ +# Trustchain APIs + +**Base URL:** `/api/v1/trust-chains` + +These endpoints allow auditors to list VP (Verifiable Presentation) documents and build full trustchains tracing a VP back to its root Verifiable Credential, enabling verification of carbon credit provenance. + +**Authentication:** All endpoints require a valid JWT Bearer token (`Authorization: Bearer `). Obtain a token via `POST /accounts/login`. Permission `AUDIT_TRUST_CHAIN_READ` is required for all endpoints. + +--- + +## Endpoints + +| Method | Endpoint | Description | Auth Required | +|--------|----------|-------------|---------------| +| GET | `/trust-chains` | Return a list of all VP documents | Yes | +| GET | `/trust-chains/{hash}` | Build and return a trustchain from a VP to the root VC | Yes | + +--- + +## Endpoint Details + +* [Requesting VP Documents](requesting.md) — `GET /trust-chains` +* [Building and Returning a Trustchain](building-and-returning.md) — `GET /trust-chains/{hash}` diff --git a/docs/trustchains-apis/building-and-returning.md b/docs/trustchains-apis/building-and-returning.md index 0fa8e09bdc..961ea3b4a6 100644 --- a/docs/trustchains-apis/building-and-returning.md +++ b/docs/trustchains-apis/building-and-returning.md @@ -1,51 +1,69 @@ -# Building and returning +# Building and Returning a Trustchain -### BUILDING AND RETURNING A TRUSTCHAIN +**`GET /trust-chains/{hash}`** -{% swagger method="get" path="" baseUrl="/trust-chains/{hash}" summary="Returns a trustchain for a VP document" %} -{% swagger-description %} -Builds and returns a trustchain, from the VP to the root VC document. Only users with the Auditor role are allowed to make the request. -{% endswagger-description %} +Builds and returns a full trustchain, tracing from a Verifiable Presentation (VP) document back to the root Verifiable Credential (VC). -{% swagger-parameter in="path" name="hash" type="String" required="true" %} -Hash or ID of a VP document -{% endswagger-parameter %} +**Authentication:** Bearer token required (`Authorization: Bearer `) -{% swagger-response status="200: OK" description="" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/TrustChains' -} -``` -{% endswagger-response %} +**Permission:** `Permissions.AUDIT_TRUST_CHAIN_READ` -{% swagger-response status="401: Unauthorized" description="" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +--- -{% swagger-response status="403: Forbidden" description="" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +## Request -{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %} -```javascript +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `hash` | string | Yes | Hash or identifier of the VP document | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +```json { - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + "chain": [ + { + "id": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "type": "VC", + "tag": "create_application", + "label": "Create Application", + "schema": "StandardRegistry", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "document": {} + } + ], + "userMap": [ + { + "did": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "username": "example_user" + } + ] } ``` -{% endswagger-response %} -{% endswagger %} + +| Field | Type | Description | +|-------|------|-------------| +| `chain` | array | Ordered list of documents from VP to root VC | +| `chain[].id` | string | Document identifier or DID | +| `chain[].type` | string | Document type: `VC`, `VP`, or `DID` | +| `chain[].tag` | string | Policy block tag that produced this document | +| `chain[].label` | string | Human-readable label | +| `chain[].schema` | string | Schema name | +| `chain[].owner` | string | DID of the document owner | +| `chain[].document` | object | The raw credential document | +| `userMap` | array | Mapping of DIDs to usernames | + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure | diff --git a/docs/trustchains-apis/requesting.md b/docs/trustchains-apis/requesting.md index 93b5bba0d5..33a2e8a969 100644 --- a/docs/trustchains-apis/requesting.md +++ b/docs/trustchains-apis/requesting.md @@ -1,49 +1,55 @@ -# Requesting - -### REQUESTS ALL VP DOCUMENTS - -{% swagger method="get" path="" baseUrl="/trust-chains" summary="Returns a list of all VP documents" %} -{% swagger-description %} -Requests all VP documents. Only users with the Auditor role are allowed to make the request -{% endswagger-description %} - -{% swagger-response status="200: OK" description="" %} -```javascript -{ - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/VerifiablePresentation' -} -``` -{% endswagger-response %} +# Requesting VP Documents -{% swagger-response status="401: Unauthorized" description="Unauthorized" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} +**`GET /trust-chains/`** -{% swagger-response status="403: Forbidden" description="" %} -```javascript -{ - // Response -} -``` -{% endswagger-response %} - -{% swagger-response status="500: Internal Server Error" description="" %} -```javascript -{ - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -} +Returns a paginated list of all Verifiable Presentation (VP) documents. + +**Authentication:** Bearer token required (`Authorization: Bearer `) + +**Permission:** `Permissions.AUDIT_TRUST_CHAIN_READ` + +--- + +## Request + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `pageIndex` | number | No | 0 | Zero-based page index | +| `pageSize` | number | No | 20 | Items per page | +| `policyId` | string | No | — | Filter by policy ID | +| `policyOwner` | string | No | — | Filter by policy owner DID | + +--- + +## Response + +### Success Response + +**Status:** `200 OK` + +The response includes an `X-Total-Count` header with the total number of matching records. + +```json +[ + { + "id": "63e3e5e8a01b3c001234abcd", + "policyId": "63e3e5e8a01b3c001234abce", + "owner": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001", + "hash": "a1b2c3d4e5f6...", + "document": { + "@context": ["https://www.w3.org/2018/credentials/v1"], + "type": ["VerifiablePresentation"] + } + } +] ``` -{% endswagger-response %} -{% endswagger %} + +### Error Responses + +| Status | Description | +|--------|-------------| +| `401 Unauthorized` | Missing or invalid token | +| `403 Forbidden` | Insufficient permissions | +| `500 Internal Server Error` | Unexpected server failure |