Policy API Documentation & DMRV Aliases

How to define human-readable API endpoint aliases?

Summary

Policy authors can define clean, human-readable API endpoint aliases for their policies, giving each integration point a simple, descriptive name instead of a raw internal URL. These aliases, along with descriptions, can be configured directly in the policy editor and are published as browsable documentation, making it easier for external systems and third-party developers to integrate with a policy's API.

---

1. Configuring API Documentation

1.1. Open the Configuration Dialog

1. Open any policy in Draft status in the Policy Configurator.
2. Click the API button in the top toolbar.

1.2. Add Endpoints

1. Click + Add Endpoint.
2. Fill in the fields for each row:

Field	Description
Block	Select a block from the dropdown list
Method	Choose BOTH, GET or POST
Name	Short name (auto-filled from block name)
Description	What the endpoint does
Alias	URL-friendly identifier. Either a single slug (new-device, create-application) or a path of slugs separated by / (monitoring-reports/create).
Preview URL	Read-only: /api/v1/dmrv/{policyId}/{alias}

1.3. Add All Endpoints

Use the Add All Endpoints button at the top of the dialog (next to + Add Endpoint) to auto-populate API documentation entries for every linked policy block in one click.

Behavior:

• Adds an entry for every eligible block in the current policy.
• Skips blocks that already have an entry — no duplicates are created.
• Generates a smart Name from the block name.
• Generates a smart Alias (URL-friendly: lowercase, hyphenated) from the block name/tag. The auto-generated alias is always a single segment; you can manually edit it into a path (e.g. monitoring-reports/create).

1.4. Validation Rules

• Alias: one or more segments of a-z, 0-9, -, separated by single /. No leading, trailing, or consecutive slashes; no empty segments. Examples: new-device, monitoring-reports/create.
• Block and Alias must be unique
• Block and Alias are required
• Method must be supported by the selected Block (GET, POST, or both for BOTH)
• GET + POST on the same Block is allowed as two separate rows; any other combination on the same Block is rejected

Errors appear below the corresponding row.

1.5. Save

1. Click Save in the modal to apply changes locally.
2. Click Save in the toolbar to persist the policy to the database.

Note: URL generation (both technical and DMRV) happens server-side on policy save.

---

2. Viewing Documentation

1. Go to Policies → Manage Policies.
2. Click the Documentation button (book icon) on a policy row.

1. The dialog shows all configured endpoints:

Column	Description
Name	Endpoint name
Description	User-provided description
Method	BOTH (blue), GET (green) or POST (orange)
URL	Technical URL to block by tag
Alias URL	External DMRV URL
Query Params	The endpoint parameters
Copy	Copies Alias URL to clipboard

---

3. Using the DMRV Proxy

3.1. Endpoint

ANY /api/v1/dmrv/:policyId/<alias-path>

<alias-path> is the configured alias as-is — a single segment (new-device) or a multi-segment path (monitoring-reports/create). The proxy captures everything after :policyId as the alias.

3.2. How It Works

Request: POST /api/v1/dmrv/{policyId}/monitoring-reports/create
            │
            ▼
   1. Capture alias path = "monitoring-reports/create"
   2. Validate alias against the rule (lowercase slug segments separated by '/')
   3. Load policy by policyId
   4. Find entry: alias="monitoring-reports/create", method="POST"
   5. Resolve: target="create_monitoring_report"
   6. Forward → setBlockDataByTag(user, policyId, "create_monitoring_report", body, ...)
   7. Return block response

3.3. Method Routing

Request Method	Internal Call	Equivalent Standard Endpoint
GET	getBlockDataByTag	GET /api/v1/policies/:id/tag/:tag/blocks
POST	setBlockDataByTag	POST /api/v1/policies/:id/tag/:tag/blocks

3.4. Authentication

Standard Bearer token. Required permissions: POLICIES_POLICY_EXECUTE, POLICIES_POLICY_MANAGE.

3.5. Response Codes

Code	Meaning
200	Success
400	Invalid alias path (does not match the slug-segments rule)
401	Unauthorized
404	Policy not found or alias not configured for this method
503	Block Unavailable (block exists but not accessible in current policy state)

3.6. Example

Request (single-segment alias):

GET /api/v1/dmrv/69c3dbe9a4d2ac84f75cdfc4/choose-role-alias
Authorization: Bearer <token>

Request (multi-segment alias):

POST /api/v1/dmrv/69c3dbe9a4d2ac84f75cdfc4/monitoring-reports/create
Authorization: Bearer <token>
Content-Type: application/json

{ "field": "value" }

Response:

{
  "id": "2326c495-eb61-4119-aeab-1a5104176457"
}

---

4. API Reference

GET /api/v1/policies/:policyId/about

Returns the configured documentation entries.

When the target block references a schema (e.g. requestVcDocumentBlock, documentValidatorBlock), the entry includes a schemaId field with the schema's IRI (without the leading #). The field is omitted for blocks that don't reference a schema.

Response example:

[
  {
    "name": "reg_form",
    "description": "reg form",
    "target": "registrant_form_grid",
    "method": "GET",
    "alias": "reg",
    "url": "/api/v1/policies/69c3dbe9a4d2ac84f75cdfc4/tag/registrant_form_grid/blocks",
    "dmrvUrl": "/api/v1/dmrv/69c3dbe9a4d2ac84f75cdfc4/reg",
    "blockType": "interfaceDocumentsSourceBlock",
    "queryParams": [
      { "name": "page",          "type": "number",   "description": "Page number (0-based)" },
      { "name": "itemsPerPage",  "type": "number",   "description": "Items per page" },
      { "name": "sortField",     "type": "string",   "description": "Field name to sort by" },
      { "name": "sortDirection", "type": "string",   "description": "Sort direction (asc/desc)" },
      { "name": "filterByUUID",  "type": "string",   "description": "Filter by document UUID" },
      { "name": "savepointIds",  "type": "string[]", "description": "Savepoint IDs filter (JSON array)" }
    ]
  },
  {
    "name": "Create Application",
    "description": "Submit a new applicant registration",
    "target": "create_application",
    "method": "POST",
    "alias": "applications/create",
    "url": "/api/v1/policies/69c3dbe9a4d2ac84f75cdfc4/tag/create_application/blocks",
    "dmrvUrl": "/api/v1/dmrv/69c3dbe9a4d2ac84f75cdfc4/applications/create",
    "blockType": "requestVcDocumentBlock",
    "schemaId": "9bd1c75b-76df-4d3c-8775-1f76d18d7d8c",
    "queryParams": []
  }
]

Related Issues

• https://github.com/hashgraph/guardian/issues/1987