Skip to content

Commit aea4207

Browse files
gayanath8OshanM
gayanath8
and
OshanM
authored
docs: 5798 5801 API & Event stream documentation and format changes
* docs: Add API endpoint documentation - Add documentation for endpoints that are currently undocumented. - Add documentation for dynamic fields defined by users. * docs: Update API documentation - Change format of API level documentation(existing ones) - Update Summary.md * docs: Modify API documentation & (API) Event Stream documentation - Fill the missing documentation gaps on some of docs - Tranform docs into formatted version remove swagger format - Modify even stream documentations * chore: add execution payload documentation md * docs: add few modifications in documentation for policy block API execution payloads * docs: update API documentation format and add missing V2 endpoint docs - Convert some docs in schema, tag from legacy GitBook format to markdown with tables and JSON examples - Add V2 endpoint documentation for: GET /schemas, GET /tools, GET /tokens, GET /policies, GET /tags/schemas, GET /schemas/system/{username}, GET /modules, GET /artifacts, POST /policies/{id}/dry-run/user, POST /projects/compare/documents, POST /contracts - Add entirely new Projects APIs section (POST /projects/search, POST /projects/compare/documents, GET /projects/properties) - Fix some of incorrect HTTP methods, permissions, response codes and paths found during format migration - Update SUMMARY.md with all new V2 doc entries and Projects section * fix: update API documentation with Block Completion Events * docs: move compare-documents-v2 into project-comparison section * - Added token-transfer API endpoint documents - Updated existing README and SUMMARY --------- Signed-off-by: gayanath8 <gayanathr@xeptagon.com> Signed-off-by: OshanM <oshanm@xeptagon.com> Co-authored-by: OshanM <oshanm@xeptagon.com>
1 parent bf931e0 commit aea4207

375 files changed

Lines changed: 18082 additions & 9036 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/SUMMARY.md‎

Lines changed: 157 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/account-apis/README.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Account APIs
2+
3+
The Account APIs handle user registration, authentication, session management, and account queries within the Guardian system.
4+
5+
**Base URL:** `/api/v1/accounts`
6+
7+
> **Note:** `POST /accounts/register`, `POST /accounts/login`, and `POST /accounts/access-token` do not require a Bearer token. All other endpoints require `Authorization: Bearer <token>`.
8+
9+
---
10+
11+
## Endpoints
12+
13+
| Method | Endpoint | Description | Auth Required |
14+
|--------|----------|-------------|---------------|
15+
| **`POST`** | `/accounts/register` | Register a new user account | No |
16+
| **`POST`** | `/accounts/login` | Log in and receive JWT tokens | No |
17+
| **`POST`** | `/accounts/change-password` | Change the authenticated user's password | Yes |
18+
| **`POST`** | `/accounts/access-token` | Refresh access token using a refresh token | No |
19+
| **`GET`** | `/accounts/session` | Return current session information | Yes |
20+
| **`GET`** | `/accounts/` | List users (excluding Standard Registry and Auditor) | Yes |
21+
| **`GET`** | `/accounts/standard-registries` | Return all Standard Registry accounts | Yes |
22+
| **`GET`** | `/accounts/standard-registries/aggregated` | Return Standard Registries with policies and VCs | Yes |
23+
| **`GET`** | `/accounts/balance` | Return the authenticated user's Hedera balance | Yes |
24+
25+
---
26+
27+
## Endpoint Details
28+
29+
* [Registering a New Account](registering-new-account.md)
30+
* [User Login](user-login.md)
31+
* [Change Password](change-password.md)
32+
* [Refresh Access Token](refresh-access-token.md)
33+
* [User Session](user-session.md)
34+
* [User Listing (Excluding Standard Registry and Auditor)](user-listing-except-root-authority-and-auditor.md)
35+
* [Returns All Standard Registries](returns-all-root-authorities.md)
36+
* [Standard Registries Aggregated](standard-registries-aggregated.md)
37+
* [User Balance](user-balance.md)

‎docs/account-apis/change-password.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Change Password
2+
3+
**`POST /accounts/change-password`**
4+
5+
Changes the authenticated user's password.
6+
7+
**Authentication:** Bearer token required (`Authorization: Bearer <token>`)
8+
9+
---
10+
11+
## Request
12+
13+
### Request Body
14+
15+
```json
16+
{
17+
"username": "example_user",
18+
"oldPassword": "examplePassword123",
19+
"newPassword": "newSecurePassword456"
20+
}
21+
```
22+
23+
| Field | Type | Required | Description |
24+
|-------|------|----------|-------------|
25+
| `username` | string | Yes | The account username |
26+
| `oldPassword` | string | Yes | The current password |
27+
| `newPassword` | string | Yes | The new password to set |
28+
29+
---
30+
31+
## Response
32+
33+
### Success Response
34+
35+
**Status:** `200 OK`
36+
37+
```json
38+
{
39+
"username": "example_user",
40+
"role": "STANDARD_REGISTRY",
41+
"did": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001",
42+
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
43+
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
44+
}
45+
```
46+
47+
### Error Responses
48+
49+
| Status | Description |
50+
|--------|-------------|
51+
| `401 Unauthorized` | Invalid credentials or missing token |
52+
| `500 Internal Server Error` | Unexpected server failure |

‎docs/account-apis/refresh-access-token.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Refresh Access Token
2+
3+
**`POST /accounts/access-token`**
4+
5+
Returns a new access token using a valid refresh token.
6+
7+
---
8+
9+
## Request
10+
11+
### Request Body
12+
13+
```json
14+
{
15+
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
16+
}
17+
```
18+
19+
| Field | Type | Required | Description |
20+
|-------|------|----------|-------------|
21+
| `refreshToken` | string | Yes | A valid refresh token obtained from login |
22+
23+
---
24+
25+
## Response
26+
27+
### Success Response
28+
29+
**Status:** `200 OK`
30+
31+
```json
32+
{
33+
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
34+
}
35+
```
36+
37+
### Error Responses
38+
39+
| Status | Description |
40+
|--------|-------------|
41+
| `401 Unauthorized` | Invalid or expired refresh token |

‎docs/account-apis/registering-new-account.md‎

Lines changed: 41 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,53 @@
1-
# Registering new account
1+
# Registering a New Account
22

3-
### REGISTERING NEW ACCOUNT
3+
**`POST /accounts/register`**
44

5-
{% swagger method="post" path="" baseUrl="/accounts/register" summary="Registers a new user account" %}
6-
{% swagger-description %}
5+
Registers a new user account with a username, password, and optional role.
76

8-
{% endswagger-description %}
7+
**Authentication:** Bearer token required for non-demo mode (`Authorization: Bearer <token>`). Only a Standard Registry user may register new accounts outside of demo mode.
98

10-
{% swagger-parameter in="body" required="true" %}
11-
Object that contain username, password and role (optional) fields
12-
{% endswagger-parameter %}
9+
---
1310

14-
{% swagger-response status="201: Created" description="Successful Operation" %}
15-
```javascript
11+
## Request
12+
13+
### Request Body
14+
15+
```json
1616
{
17-
content:
18-
application/json:
19-
schema:
20-
$ref: '#/components/schemas/Account'
17+
"username": "example_user",
18+
"password": "examplePassword123",
19+
"role": "USER"
2120
}
2221
```
23-
{% endswagger-response %}
2422

25-
{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %}
26-
```javascript
23+
| Field | Type | Required | Description |
24+
|-------|------|----------|-------------|
25+
| `username` | string | Yes | The new account username |
26+
| `password` | string | Yes | The account password |
27+
| `role` | string | No | User role: `STANDARD_REGISTRY`, `USER`, or `AUDITOR`. Defaults to `USER` |
28+
29+
---
30+
31+
## Response
32+
33+
### Success Response
34+
35+
**Status:** `201 Created`
36+
37+
```json
2738
{
28-
content:
29-
application/json:
30-
schema:
31-
$ref: '#/components/schemas/Error'
39+
"username": "example_user",
40+
"role": "USER",
41+
"did": null,
42+
"hederaAccountId": null
3243
}
3344
```
34-
{% endswagger-response %}
35-
{% endswagger %}
45+
46+
### Error Responses
47+
48+
| Status | Description |
49+
|--------|-------------|
50+
| `401 Unauthorized` | Caller is not authenticated (non-demo mode) |
51+
| `403 Forbidden` | Caller does not have Standard Registry role |
52+
| `409 Conflict` | Username already exists |
53+
| `500 Internal Server Error` | Unexpected server failure |

‎docs/account-apis/returns-all-root-authorities.md‎

Lines changed: 42 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,44 @@
1-
# Returns all Standard Registries
2-
3-
{% swagger method="get" path="" baseUrl="/accounts/standard-registries" summary="Returns an array of Standard Registries for user to select one during registration process" %}
4-
{% swagger-description %}
5-
Returns all Standard Registries
6-
{% endswagger-description %}
7-
8-
{% swagger-response status="200: OK" description="Successful Operation" %}
9-
```javascript
10-
{
11-
content:
12-
application/json:
13-
schema:
14-
type: array
15-
items:
16-
$ref: '#/components/schemas/Account'
17-
}
18-
```
19-
{% endswagger-response %}
1+
# Returns All Standard Registries
202

21-
{% swagger-response status="401: Unauthorized" description="Unauthorized" %}
22-
```javascript
23-
{
24-
// Response
25-
}
26-
```
27-
{% endswagger-response %}
28-
29-
{% swagger-response status="500: Internal Server Error" description="Internal Server Error" %}
30-
```javascript
31-
{
32-
content:
33-
application/json:
34-
schema:
35-
$ref: '#/components/schemas/Error'
36-
}
3+
**`GET /accounts/standard-registries`**
4+
5+
Returns all Standard Registry accounts available in the system.
6+
7+
**Authentication:** Bearer token required (`Authorization: Bearer <token>`)
8+
9+
**Permission:** `Permissions.ACCOUNTS_STANDARD_REGISTRY_READ`
10+
11+
---
12+
13+
## Request
14+
15+
No request body or parameters required.
16+
17+
---
18+
19+
## Response
20+
21+
### Success Response
22+
23+
**Status:** `200 OK`
24+
25+
```json
26+
[
27+
{
28+
"username": "registry_user",
29+
"role": "STANDARD_REGISTRY",
30+
"did": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001",
31+
"hederaAccountId": "0.0.4532001",
32+
"confirmed": true,
33+
"failed": false
34+
}
35+
]
3736
```
38-
{% endswagger-response %}
39-
{% endswagger %}
37+
38+
### Error Responses
39+
40+
| Status | Description |
41+
|--------|-------------|
42+
| `401 Unauthorized` | Missing or invalid token |
43+
| `403 Forbidden` | Insufficient permissions |
44+
| `500 Internal Server Error` | Unexpected server failure |

‎docs/account-apis/standard-registries-aggregated.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Standard Registries Aggregated
2+
3+
**`GET /accounts/standard-registries/aggregated`**
4+
5+
Returns all Standard Registry accounts aggregated with their associated policies and VC documents.
6+
7+
**Authentication:** Bearer token required (`Authorization: Bearer <token>`)
8+
9+
**Permission:** `Permissions.ACCOUNTS_STANDARD_REGISTRY_READ`
10+
11+
---
12+
13+
## Request
14+
15+
No request body or parameters required.
16+
17+
---
18+
19+
## Response
20+
21+
### Success Response
22+
23+
**Status:** `200 OK`
24+
25+
```json
26+
[
27+
{
28+
"did": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001",
29+
"username": "registry_user",
30+
"hederaAccountId": "0.0.4532001",
31+
"vcDocument": {
32+
"@context": ["https://www.w3.org/2018/credentials/v1"],
33+
"id": "did:hedera:testnet:zHcDLGFNymFAJiMBKnpbHDgjvTn6yZnwkPPeFhtJBECH_0.0.4532001",
34+
"type": ["VerifiableCredential"]
35+
},
36+
"policies": [
37+
{
38+
"id": "63e3e5e8a01b3c001234abcd",
39+
"name": "Example Policy",
40+
"version": "1.0.0",
41+
"status": "PUBLISH"
42+
}
43+
]
44+
}
45+
]
46+
```
47+
48+
### Error Responses
49+
50+
| Status | Description |
51+
|--------|-------------|
52+
| `401 Unauthorized` | Missing or invalid token |
53+
| `403 Forbidden` | Insufficient permissions |
54+
| `500 Internal Server Error` | Unexpected server failure |

0 commit comments

Comments
 (0)
⚡