From 98237f1af15d1704e863673c182a56978372e6c9 Mon Sep 17 00:00:00 2001 From: danielporterda Date: Wed, 8 Apr 2026 15:40:32 -0400 Subject: [PATCH 1/2] Make OpenAPI reference path-first --- src/x2mdx/openapi/render.py | 130 +++++- .../openapi/endpoint_reference.md.j2 | 12 +- .../openapi/expected/json-api-reference.mdx | 428 +++++++++++++----- tests/test_openapi.py | 64 ++- tests/test_openapi_published_fixtures.py | 3 + 5 files changed, 495 insertions(+), 142 deletions(-) diff --git a/src/x2mdx/openapi/render.py b/src/x2mdx/openapi/render.py index 8e30e80..1472445 100644 --- a/src/x2mdx/openapi/render.py +++ b/src/x2mdx/openapi/render.py @@ -252,26 +252,122 @@ def operation_change_summary_value(spec: OpenApiSpecLifecycle, lifecycle: OpenAp return f"{shown}; +{len(version_summaries) - 3} more" -def table_of_contents_rows(spec: OpenApiSpecLifecycle) -> list[list[str]]: +def path_name(operation: dict[str, Any]) -> str: + return str(operation.get("path", "")).strip() + + +def path_anchor_id(path: str) -> str: + return f"path-{slugify(path)}" + + +def path_anchor_link(path: str) -> str: + return f"[{md_code(path)}](#{path_anchor_id(path)})" + + +def _latest_operation_groups( + spec: OpenApiSpecLifecycle, operations: list[dict[str, Any]] | None = None +) -> list[dict[str, Any]]: lifecycle_by_key = { record.entity_key: record for record in spec.entity_lifecycle if record.entity_type == "operation" } - rows: list[list[str]] = [] - for operation in spec.latest_operation_details: + grouped_by_path: dict[str, dict[str, Any]] = {} + groups: list[dict[str, Any]] = [] + for operation in operations or spec.latest_operation_details: + path = path_name(operation) + group = grouped_by_path.get(path) + if group is None: + group = { + "path": path, + "path_anchor_id": path_anchor_id(path), + "operations": [], + } + grouped_by_path[path] = group + groups.append(group) entity_key = str(operation.get("entity_key", "") or "") - lifecycle = lifecycle_by_key.get(entity_key) + group["operations"].append( + { + "operation": operation, + "lifecycle": lifecycle_by_key.get(entity_key), + } + ) + return groups + + +def _earliest_version(spec: OpenApiSpecLifecycle, versions: list[str]) -> str | None: + if not versions: + return None + version_order = {version: index for index, version in enumerate(spec.versions_present)} + return min(versions, key=lambda version: version_order.get(version, len(version_order))) + + +def path_summary_text(group_operations: list[dict[str, Any]]) -> str: + if not group_operations: + return "-" + if len(group_operations) == 1: + return operation_summary_text(group_operations[0]["operation"]) + + parts: list[str] = [] + for item in group_operations: + operation = item["operation"] + method = str(operation.get("method", "")).strip().upper() or "METHOD" + summary = operation_summary_text(operation) + parts.append(method if summary == "-" else f"{method}: {summary}") + + if len(parts) <= 2: + return "; ".join(parts) + shown = "; ".join(parts[:2]) + return f"{shown}; +{len(parts) - 2} more" + + +def path_change_summary_value(spec: OpenApiSpecLifecycle, group_operations: list[dict[str, Any]]) -> str: + summaries: list[str] = [] + for item in group_operations: + lifecycle = item["lifecycle"] if lifecycle is None: continue + summary = operation_change_summary_value(spec, lifecycle) + if summary == "-": + continue + method = str(item["operation"].get("method", "")).strip().upper() or "METHOD" + summaries.append(f"{method} {summary}") + + if not summaries: + return "-" + if len(summaries) <= 3: + return "; ".join(summaries) + shown = "; ".join(summaries[:3]) + return f"{shown}; +{len(summaries) - 3} more" + + +def table_of_contents_rows(spec: OpenApiSpecLifecycle) -> list[list[str]]: + rows: list[list[str]] = [] + for group in _latest_operation_groups(spec): + introduced_version = _earliest_version( + spec, + [ + str(item["lifecycle"].introduced_version) + for item in group["operations"] + if item["lifecycle"] is not None and item["lifecycle"].introduced_version + ], + ) + removed_version = _earliest_version( + spec, + [ + str(item["lifecycle"].removed_version) + for item in group["operations"] + if item["lifecycle"] is not None and item["lifecycle"].removed_version + ], + ) rows.append( [ - endpoint_anchor_link(endpoint_name(operation)), - operation_summary_text(operation), - lifecycle_value(lifecycle.introduced_version, "introduced"), - operation_change_summary_value(spec, lifecycle), + path_anchor_link(str(group["path"])), + path_summary_text(group["operations"]), + lifecycle_value(introduced_version, "introduced"), + path_change_summary_value(spec, group["operations"]), "-", - lifecycle_value(lifecycle.removed_version, "removed"), + lifecycle_value(removed_version, "removed"), ] ) return rows @@ -333,7 +429,7 @@ def _endpoint_reference_operation(operation: dict[str, Any]) -> dict[str, Any]: return { "anchor_id": endpoint_anchor_id(endpoint), - "header": endpoint_header(operation), + "header": md_code(str(operation.get("method", "")).strip().upper() or "-"), "bullet_items": [ item for item in [ @@ -374,12 +470,20 @@ def _endpoint_reference_operation(operation: dict[str, Any]) -> dict[str, Any]: } -def render_endpoint_reference(operations: list[dict[str, Any]], max_endpoints: int) -> str: +def render_endpoint_reference(spec: OpenApiSpecLifecycle, operations: list[dict[str, Any]], max_endpoints: int) -> str: if not operations: return "No endpoint details available in the latest spec." + path_groups = [ + { + "anchor_id": str(group["path_anchor_id"]), + "header": md_code(str(group["path"])), + "operations": [_endpoint_reference_operation(item["operation"]) for item in group["operations"]], + } + for group in _latest_operation_groups(spec, operations[:max_endpoints]) + ] return render_template( "openapi/endpoint_reference.md.j2", - operations=[_endpoint_reference_operation(operation) for operation in operations[:max_endpoints]], + path_groups=path_groups, max_endpoints=max_endpoints, total_operations=len(operations), ) @@ -399,7 +503,7 @@ def build_spec_page(spec: OpenApiSpecLifecycle, spec_dir_name: str) -> Page: table_of_contents_rows=toc_rows[:MAX_TABLE_OF_CONTENTS_ROWS], table_of_contents_total=len(toc_rows), table_of_contents_limit=MAX_TABLE_OF_CONTENTS_ROWS, - endpoint_reference=render_endpoint_reference(spec.latest_operation_details, MAX_ENDPOINTS), + endpoint_reference=render_endpoint_reference(spec, spec.latest_operation_details, MAX_ENDPOINTS), version_timeline_rows=[ [ md_code(version), diff --git a/src/x2mdx/templates/openapi/endpoint_reference.md.j2 b/src/x2mdx/templates/openapi/endpoint_reference.md.j2 index 2e57d54..65105d9 100644 --- a/src/x2mdx/templates/openapi/endpoint_reference.md.j2 +++ b/src/x2mdx/templates/openapi/endpoint_reference.md.j2 @@ -1,7 +1,11 @@ -{% for operation in operations %} +{% for path_group in path_groups %} +{{ anchor(path_group.anchor_id) }} + +{{ heading(3, path_group.header) }} +{% for operation in path_group.operations %} {{ anchor(operation.anchor_id) }} -{{ heading(3, operation.header) }} +{{ heading(4, operation.header) }} {% if operation.bullet_items %} {{ bullet_list(operation.bullet_items) }} {% endif %} @@ -32,6 +36,10 @@ {% endif %} {% if not loop.last %} +{% endif %} +{% endfor %} +{% if not loop.last %} + {% endif %} {% endfor %} {% if total_operations > max_endpoints %} diff --git a/tests/fixtures/characterization/openapi/expected/json-api-reference.mdx b/tests/fixtures/characterization/openapi/expected/json-api-reference.mdx index 4973b6a..78282fa 100644 --- a/tests/fixtures/characterization/openapi/expected/json-api-reference.mdx +++ b/tests/fixtures/characterization/openapi/expected/json-api-reference.mdx @@ -9,74 +9,66 @@ Generated from supplied versioned OpenAPI artifacts. | Name | Summary | Introduced | Changed | Deprecated | Removed | | --- | --- | --- | --- | --- | --- | -| [`GET /livez`](#endpoint-get-livez) | Checks if the service is alive | `3.5` | - | - | - | -| [`GET /readyz`](#endpoint-get-readyz) | Checks if the service is ready to serve requests | `3.5` | - | - | - | -| [`GET /v2/authenticated-user`](#endpoint-get-v2-authenticated-user) | Get the user data of the current authenticated user. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`POST /v2/commands/async/submit`](#endpoint-post-v2-commands-async-submit) | Submit a single composite command. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`POST /v2/commands/async/submit-reassignment`](#endpoint-post-v2-commands-async-submit-reassignment) | Submit a single reassignment. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`POST /v2/commands/completions`](#endpoint-post-v2-commands-completions) | Query completions list (blocking call) Subscribe to command completion events. Notice: This endpoint should be used for small results set. When number of results exceeded node configuration limit (`http-list-max-elements-limit`) there will be an error (`413 Content Too Large`) returned. Increasing this limit may lead to performance issues and high memory consumption. Consider using websockets (asyncapi) for better efficiency with larger results. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`POST /v2/commands/submit-and-wait`](#endpoint-post-v2-commands-submit-and-wait) | Submits a single composite command and waits for its result. Propagates the gRPC error of failed submissions including Daml interpretation errors. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`POST /v2/commands/submit-and-wait-for-reassignment`](#endpoint-post-v2-commands-submit-and-wait-for-reassignment) | Submits a single composite reassignment command, waits for its result, and returns the reassignment. Propagates the gRPC error of failed submission. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`POST /v2/commands/submit-and-wait-for-transaction`](#endpoint-post-v2-commands-submit-and-wait-for-transaction) | Submits a single composite command, waits for its result, and returns the transaction. Propagates the gRPC error of failed submissions including Daml interpretation errors. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`POST /v2/commands/submit-and-wait-for-transaction-tree`](#endpoint-post-v2-commands-submit-and-wait-for-transaction-tree) | Submit a batch of commands and wait for the transaction trees response. Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use submit-and-wait-for-transaction instead. | `3.4` | 3.5: response `400` description updated | - | - | -| [`POST /v2/contracts/contract-by-id`](#endpoint-post-v2-contracts-contract-by-id) | Looking up contract data by contract ID. This endpoint is experimental / alpha, therefore no backwards compatibility is guaranteed. This endpoint must not be used to look up contracts which entered the participant via party replication or repair service. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`POST /v2/dars`](#endpoint-post-v2-dars) | Upload a DAR to the participant node | `3.4` | 3.5: response `400` description updated | - | - | -| [`POST /v2/dars/validate`](#endpoint-post-v2-dars-validate) | Validates the DAR and checks the upgrade compatibility of the DAR's packages with the set of the already vetted packages on the target vetting synchronizer. See ValidateDarFileRequest for details regarding the target vetting synchronizer. The operation has no effect on the state of the participant or the Canton ledger: the DAR payload and its packages are not persisted neither are the packages vetted. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`POST /v2/events/events-by-contract-id`](#endpoint-post-v2-events-events-by-contract-id) | Get the create and the consuming exercise event for the contract with the provided ID. No events will be returned for contracts that have been pruned because they have already been archived before the latest pruning offset. If the contract cannot be found for the request, or all the contract-events are filtered, a CONTRACT_EVENTS_NOT_FOUND error will be raised. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`GET /v2/idps`](#endpoint-get-v2-idps) | List all existing identity provider configurations. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`POST /v2/idps`](#endpoint-post-v2-idps) | Create a new identity provider configuration. The request will fail if the maximum allowed number of separate configurations is reached. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`DELETE /v2/idps/{idp-id}`](#endpoint-delete-v2-idps-idp-id) | Delete an existing identity provider configuration. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`GET /v2/idps/{idp-id}`](#endpoint-get-v2-idps-idp-id) | Get the identity provider configuration data by id. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`PATCH /v2/idps/{idp-id}`](#endpoint-patch-v2-idps-idp-id) | Update selected modifiable attribute of an identity provider config resource described by the ``IdentityProviderConfig`` message. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`POST /v2/interactive-submission/execute`](#endpoint-post-v2-interactive-submission-execute) | Execute a prepared submission _asynchronously_ on the ledger. Requires a signature of the transaction from the submitting external party. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`POST /v2/interactive-submission/executeAndWait`](#endpoint-post-v2-interactive-submission-executeandwait) | Similar to ExecuteSubmission but _synchronously_ wait for the completion of the transaction IMPORTANT: Relying on the response from this endpoint requires trusting the Participant Node to be honest. A malicious node could make a successfully committed request appeared failed and vice versa | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`POST /v2/interactive-submission/executeAndWaitForTransaction`](#endpoint-post-v2-interactive-submission-executeandwaitfortransaction) | Similar to ExecuteSubmissionAndWait but additionally returns the transaction IMPORTANT: Relying on the response from this endpoint requires trusting the Participant Node to be honest. A malicious node could make a successfully committed request appear as failed and vice versa | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`GET /v2/interactive-submission/preferred-package-version`](#endpoint-get-v2-interactive-submission-preferred-package-version) | A preferred package is the highest-versioned package for a provided package-name that is vetted by all the participants hosting the provided parties. Ledger API clients should use this endpoint for constructing command submissions that are compatible with the provided preferred package, by making informed decisions on: - which are the compatible packages that can be used to create contracts - which contract or exercise choice argument version can be used in the command - which choices can be executed on a template or interface of a contract Can be accessed by any Ledger API client with a valid token when Ledger API authorization is enabled. Provided for backwards compatibility, it will be removed in the Canton version 3.4.0 | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`POST /v2/interactive-submission/preferred-packages`](#endpoint-post-v2-interactive-submission-preferred-packages) | Compute the preferred packages for the vetting requirements in the request. A preferred package is the highest-versioned package for a provided package-name that is vetted by all the participants hosting the provided parties. Ledger API clients should use this endpoint for constructing command submissions that are compatible with the provided preferred packages, by making informed decisions on: - which are the compatible packages that can be used to create contracts - which contract or exercise choice argument version can be used in the command - which choices can be executed on a template or interface of a contract If the package preferences could not be computed due to no selection satisfying the requirements, a `FAILED_PRECONDITION` error will be returned. Can be accessed by any Ledger API client with a valid token when Ledger API authorization is enabled. Experimental API: this endpoint is not guaranteed to provide backwards compatibility in future releases | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`POST /v2/interactive-submission/prepare`](#endpoint-post-v2-interactive-submission-prepare) | Requires `readAs` scope for the submitting party when LAPI User authorization is enabled | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`GET /v2/package-vetting`](#endpoint-get-v2-package-vetting) | Lists which participant node vetted what packages on which synchronizer. Can be called by any authenticated user. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`POST /v2/package-vetting`](#endpoint-post-v2-package-vetting) | Update the vetted packages of this participant | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`GET /v2/packages`](#endpoint-get-v2-packages) | Returns the identifiers of all supported packages. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`POST /v2/packages`](#endpoint-post-v2-packages) | Behaves the same as /dars. This endpoint will be deprecated and removed in a future release. Upload a DAR file to the participant. If vetting is enabled in the request, the DAR is checked for upgrade compatibility with the set of the already vetted packages on the target vetting synchronizer See UploadDarFileRequest for details regarding vetting and the target vetting synchronizer. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`GET /v2/packages/{package-id}`](#endpoint-get-v2-packages-package-id) | Returns the contents of a single package. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`GET /v2/packages/{package-id}/status`](#endpoint-get-v2-packages-package-id-status) | Returns the status of a single package. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`GET /v2/parties`](#endpoint-get-v2-parties) | List the parties known by the participant. The list returned contains parties whose ledger access is facilitated by the participant and the ones maintained elsewhere. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`POST /v2/parties`](#endpoint-post-v2-parties) | Allocates a new party on a ledger and adds it to the set managed by the participant. Caller specifies a party identifier suggestion, the actual identifier allocated might be different and is implementation specific. Caller can specify party metadata that is stored locally on the participant. This call may: - Succeed, in which case the actual allocated identifier is visible in the response. - Respond with a gRPC error daml-on-kv-ledger: suggestion's uniqueness is checked by the validators in the consensus layer and call rejected if the identifier is already present. canton: completely different globally unique identifier is allocated. Behind the scenes calls to an internal protocol are made. As that protocol is richer than the surface protocol, the arguments take implicit values The party identifier suggestion must be a valid party name. Party names are required to be non-empty US-ASCII strings built from letters, digits, space, colon, minus and underscore limited to 255 chars | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`POST /v2/parties/external/allocate`](#endpoint-post-v2-parties-external-allocate) | Alpha 3.3: Endpoint to allocate a new external party on a synchronizer Expected to be stable in 3.5 The external party must be hosted (at least) on this node with either confirmation or observation permissions It can optionally be hosted on other nodes (then called a multi-hosted party). If hosted on additional nodes, explicit authorization of the hosting relationship must be performed on those nodes before the party can be used. Decentralized namespaces are supported but must be provided fully authorized by their owners. The individual owner namespace transactions can be submitted in the same call (fully authorized as well). In the simple case of a non-multi hosted, non-decentralized party, the RPC will return once the party is effectively allocated and ready to use, similarly to the AllocateParty behavior. For more complex scenarios applications may need to query the party status explicitly (only through the admin API as of now). | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`POST /v2/parties/external/generate-topology`](#endpoint-post-v2-parties-external-generate-topology) | Alpha 3.3: Convenience endpoint to generate topology transactions for external signing Expected to be stable in 3.5 You may use this endpoint to generate the common external topology transactions which can be signed externally and uploaded as part of the allocate party process Note that this request will create a normal namespace using the same key for the identity as for signing. More elaborate schemes such as multi-signature or decentralized parties require you to construct the topology transactions yourself. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`GET /v2/parties/participant-id`](#endpoint-get-v2-parties-participant-id) | Return the identifier of the participant. All horizontally scaled replicas should return the same id. daml-on-kv-ledger: returns an identifier supplied on command line at launch time canton: returns globally unique identifier of the participant | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`GET /v2/parties/{party}`](#endpoint-get-v2-parties-party) | Get the party details of the given parties. Only known parties will be returned in the list. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`PATCH /v2/parties/{party}`](#endpoint-patch-v2-parties-party) | Update selected modifiable participant-local attributes of a party details resource. Can update the participant's local information for local parties. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`POST /v2/state/active-contracts`](#endpoint-post-v2-state-active-contracts) | Query active contracts list (blocking call). Querying active contracts is an expensive operation and if possible should not be repeated often. Consider querying active contracts initially (for a given offset) and then repeatedly call one of `/v2/updates/...`endpoints to get subsequent modifications. You can also use websockets to get updates with better performance. Returns a stream of the snapshot of the active contracts and incomplete (un)assignments at a ledger offset. Once the stream of GetActiveContractsResponses completes, the client SHOULD begin streaming updates from the update service, starting at the GetActiveContractsRequest.active_at_offset specified in this request. Clients SHOULD NOT assume that the set of active contracts they receive reflects the state at the ledger end. Notice: This endpoint should be used for small results set. When number of results exceeded node configuration limit (`http-list-max-elements-limit`) there will be an error (`413 Content Too Large`) returned. Increasing this limit may lead to performance issues and high memory consumption. Consider using websockets (asyncapi) for better efficiency with larger results. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`GET /v2/state/connected-synchronizers`](#endpoint-get-v2-state-connected-synchronizers) | Get the list of connected synchronizers at the time of the query. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`GET /v2/state/latest-pruned-offsets`](#endpoint-get-v2-state-latest-pruned-offsets) | Get the latest successfully pruned ledger offsets | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`GET /v2/state/ledger-end`](#endpoint-get-v2-state-ledger-end) | Get the current ledger end. Subscriptions started with the returned offset will serve events after this RPC was called. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`POST /v2/updates`](#endpoint-post-v2-updates) | Read the ledger's filtered update stream for the specified contents and filters. It returns the event types in accordance with the stream contents selected. Also the selection criteria for individual events depends on the transaction shape chosen. - ACS delta: a requesting party must be a stakeholder of an event for it to be included. - ledger effects: a requesting party must be a witness of an event for it to be included. Notice: This endpoint should be used for small results set. When number of results exceeded node configuration limit (`http-list-max-elements-limit`) there will be an error (`413 Content Too Large`) returned. Increasing this limit may lead to performance issues and high memory consumption. Consider using websockets (asyncapi) for better efficiency with larger results. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`POST /v2/updates/flats`](#endpoint-post-v2-updates-flats) | Query flat transactions update list (blocking call). Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use v2/updates instead. Notice: This endpoint should be used for small results set. When number of results exceeded node configuration limit (`http-list-max-elements-limit`) there will be an error (`413 Content Too Large`) returned. Increasing this limit may lead to performance issues and high memory consumption. Consider using websockets (asyncapi) for better efficiency with larger results. | `3.4` | 3.5: response `400` description updated | - | - | -| [`POST /v2/updates/transaction-by-id`](#endpoint-post-v2-updates-transaction-by-id) | Get transaction by id. Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use v2/updates/update-by-id instead. | `3.4` | 3.5: response `400` description updated | - | - | -| [`POST /v2/updates/transaction-by-offset`](#endpoint-post-v2-updates-transaction-by-offset) | Get transaction by offset. Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use v2/updates/update-by-offset instead. | `3.4` | 3.5: response `400` description updated | - | - | -| [`GET /v2/updates/transaction-tree-by-id/{update-id}`](#endpoint-get-v2-updates-transaction-tree-by-id-update-id) | Get transaction tree by id. Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use v2/updates/update-by-id instead. | `3.4` | 3.5: response `400` description updated | - | - | -| [`GET /v2/updates/transaction-tree-by-offset/{offset}`](#endpoint-get-v2-updates-transaction-tree-by-offset-offset) | Get transaction tree by offset. Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use v2/updates/update-by-offset instead. | `3.4` | 3.5: response `400` description updated | - | - | -| [`POST /v2/updates/trees`](#endpoint-post-v2-updates-trees) | Query update transactions tree list (blocking call). Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use v2/updates instead. Notice: This endpoint should be used for small results set. When number of results exceeded node configuration limit (`http-list-max-elements-limit`) there will be an error (`413 Content Too Large`) returned. Increasing this limit may lead to performance issues and high memory consumption. Consider using websockets (asyncapi) for better efficiency with larger results. | `3.4` | 3.5: response `400` description updated | - | - | -| [`POST /v2/updates/update-by-id`](#endpoint-post-v2-updates-update-by-id) | Lookup an update by its ID. If there is no update with this ID, or all the events are filtered, an UPDATE_NOT_FOUND error will be raised. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`POST /v2/updates/update-by-offset`](#endpoint-post-v2-updates-update-by-offset) | Lookup an update by its offset. If there is no update with this offset, or all the events are filtered, an UPDATE_NOT_FOUND error will be raised. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`GET /v2/users`](#endpoint-get-v2-users) | List all existing users. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`POST /v2/users`](#endpoint-post-v2-users) | Create a new user. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`DELETE /v2/users/{user-id}`](#endpoint-delete-v2-users-user-id) | Delete an existing user and all its rights. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`GET /v2/users/{user-id}`](#endpoint-get-v2-users-user-id) | Get the user data of a specific user or the authenticated user. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`PATCH /v2/users/{user-id}`](#endpoint-patch-v2-users-user-id) | Update selected modifiable attribute of a user resource described by the ``User`` message. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`PATCH /v2/users/{user-id}/identity-provider-id`](#endpoint-patch-v2-users-user-id-identity-provider-id) | Update the assignment of a user from one IDP to another. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`GET /v2/users/{user-id}/rights`](#endpoint-get-v2-users-user-id-rights) | List the set of all rights granted to a user. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`PATCH /v2/users/{user-id}/rights`](#endpoint-patch-v2-users-user-id-rights) | Revoke rights from a user. Revoking rights does not affect the resource version of the corresponding user. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`POST /v2/users/{user-id}/rights`](#endpoint-post-v2-users-user-id-rights) | Grant rights to a user. Granting rights does not affect the resource version of the corresponding user. | `3.4` | 3.5: description updated; response `400` description updated | - | - | -| [`GET /v2/version`](#endpoint-get-v2-version) | Read the Ledger API version | `3.4` | 3.5: description updated; response `400` description updated | - | - | +| [`/livez`](#path-livez) | Checks if the service is alive | `3.5` | - | - | - | +| [`/readyz`](#path-readyz) | Checks if the service is ready to serve requests | `3.5` | - | - | - | +| [`/v2/authenticated-user`](#path-v2-authenticated-user) | Get the user data of the current authenticated user. | `3.4` | GET 3.5: description updated; response `400` description updated | - | - | +| [`/v2/commands/async/submit`](#path-v2-commands-async-submit) | Submit a single composite command. | `3.4` | POST 3.5: description updated; response `400` description updated | - | - | +| [`/v2/commands/async/submit-reassignment`](#path-v2-commands-async-submit-reassignment) | Submit a single reassignment. | `3.4` | POST 3.5: description updated; response `400` description updated | - | - | +| [`/v2/commands/completions`](#path-v2-commands-completions) | Query completions list (blocking call) Subscribe to command completion events. Notice: This endpoint should be used for small results set. When number of results exceeded node configuration limit (`http-list-max-elements-limit`) there will be an error (`413 Content Too Large`) returned. Increasing this limit may lead to performance issues and high memory consumption. Consider using websockets (asyncapi) for better efficiency with larger results. | `3.4` | POST 3.5: description updated; response `400` description updated | - | - | +| [`/v2/commands/submit-and-wait`](#path-v2-commands-submit-and-wait) | Submits a single composite command and waits for its result. Propagates the gRPC error of failed submissions including Daml interpretation errors. | `3.4` | POST 3.5: description updated; response `400` description updated | - | - | +| [`/v2/commands/submit-and-wait-for-reassignment`](#path-v2-commands-submit-and-wait-for-reassignment) | Submits a single composite reassignment command, waits for its result, and returns the reassignment. Propagates the gRPC error of failed submission. | `3.4` | POST 3.5: description updated; response `400` description updated | - | - | +| [`/v2/commands/submit-and-wait-for-transaction`](#path-v2-commands-submit-and-wait-for-transaction) | Submits a single composite command, waits for its result, and returns the transaction. Propagates the gRPC error of failed submissions including Daml interpretation errors. | `3.4` | POST 3.5: description updated; response `400` description updated | - | - | +| [`/v2/commands/submit-and-wait-for-transaction-tree`](#path-v2-commands-submit-and-wait-for-transaction-tree) | Submit a batch of commands and wait for the transaction trees response. Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use submit-and-wait-for-transaction instead. | `3.4` | POST 3.5: response `400` description updated | - | - | +| [`/v2/contracts/contract-by-id`](#path-v2-contracts-contract-by-id) | Looking up contract data by contract ID. This endpoint is experimental / alpha, therefore no backwards compatibility is guaranteed. This endpoint must not be used to look up contracts which entered the participant via party replication or repair service. | `3.4` | POST 3.5: description updated; response `400` description updated | - | - | +| [`/v2/dars`](#path-v2-dars) | Upload a DAR to the participant node | `3.4` | POST 3.5: response `400` description updated | - | - | +| [`/v2/dars/validate`](#path-v2-dars-validate) | Validates the DAR and checks the upgrade compatibility of the DAR's packages with the set of the already vetted packages on the target vetting synchronizer. See ValidateDarFileRequest for details regarding the target vetting synchronizer. The operation has no effect on the state of the participant or the Canton ledger: the DAR payload and its packages are not persisted neither are the packages vetted. | `3.4` | POST 3.5: description updated; response `400` description updated | - | - | +| [`/v2/events/events-by-contract-id`](#path-v2-events-events-by-contract-id) | Get the create and the consuming exercise event for the contract with the provided ID. No events will be returned for contracts that have been pruned because they have already been archived before the latest pruning offset. If the contract cannot be found for the request, or all the contract-events are filtered, a CONTRACT_EVENTS_NOT_FOUND error will be raised. | `3.4` | POST 3.5: description updated; response `400` description updated | - | - | +| [`/v2/idps`](#path-v2-idps) | GET: List all existing identity provider configurations.; POST: Create a new identity provider configuration. The request will fail if the maximum allowed number of separate configurations is reached. | `3.4` | GET 3.5: description updated; response `400` description updated; POST 3.5: description updated; response `400` description updated | - | - | +| [`/v2/idps/{idp-id}`](#path-v2-idps-idp-id) | DELETE: Delete an existing identity provider configuration.; GET: Get the identity provider configuration data by id.; +1 more | `3.4` | DELETE 3.5: description updated; response `400` description updated; GET 3.5: description updated; response `400` description updated; PATCH 3.5: description updated; response `400` description updated | - | - | +| [`/v2/interactive-submission/execute`](#path-v2-interactive-submission-execute) | Execute a prepared submission _asynchronously_ on the ledger. Requires a signature of the transaction from the submitting external party. | `3.4` | POST 3.5: description updated; response `400` description updated | - | - | +| [`/v2/interactive-submission/executeAndWait`](#path-v2-interactive-submission-executeandwait) | Similar to ExecuteSubmission but _synchronously_ wait for the completion of the transaction IMPORTANT: Relying on the response from this endpoint requires trusting the Participant Node to be honest. A malicious node could make a successfully committed request appeared failed and vice versa | `3.4` | POST 3.5: description updated; response `400` description updated | - | - | +| [`/v2/interactive-submission/executeAndWaitForTransaction`](#path-v2-interactive-submission-executeandwaitfortransaction) | Similar to ExecuteSubmissionAndWait but additionally returns the transaction IMPORTANT: Relying on the response from this endpoint requires trusting the Participant Node to be honest. A malicious node could make a successfully committed request appear as failed and vice versa | `3.4` | POST 3.5: description updated; response `400` description updated | - | - | +| [`/v2/interactive-submission/preferred-package-version`](#path-v2-interactive-submission-preferred-package-version) | A preferred package is the highest-versioned package for a provided package-name that is vetted by all the participants hosting the provided parties. Ledger API clients should use this endpoint for constructing command submissions that are compatible with the provided preferred package, by making informed decisions on: - which are the compatible packages that can be used to create contracts - which contract or exercise choice argument version can be used in the command - which choices can be executed on a template or interface of a contract Can be accessed by any Ledger API client with a valid token when Ledger API authorization is enabled. Provided for backwards compatibility, it will be removed in the Canton version 3.4.0 | `3.4` | GET 3.5: description updated; response `400` description updated | - | - | +| [`/v2/interactive-submission/preferred-packages`](#path-v2-interactive-submission-preferred-packages) | Compute the preferred packages for the vetting requirements in the request. A preferred package is the highest-versioned package for a provided package-name that is vetted by all the participants hosting the provided parties. Ledger API clients should use this endpoint for constructing command submissions that are compatible with the provided preferred packages, by making informed decisions on: - which are the compatible packages that can be used to create contracts - which contract or exercise choice argument version can be used in the command - which choices can be executed on a template or interface of a contract If the package preferences could not be computed due to no selection satisfying the requirements, a `FAILED_PRECONDITION` error will be returned. Can be accessed by any Ledger API client with a valid token when Ledger API authorization is enabled. Experimental API: this endpoint is not guaranteed to provide backwards compatibility in future releases | `3.4` | POST 3.5: description updated; response `400` description updated | - | - | +| [`/v2/interactive-submission/prepare`](#path-v2-interactive-submission-prepare) | Requires `readAs` scope for the submitting party when LAPI User authorization is enabled | `3.4` | POST 3.5: description updated; response `400` description updated | - | - | +| [`/v2/package-vetting`](#path-v2-package-vetting) | GET: Lists which participant node vetted what packages on which synchronizer. Can be called by any authenticated user.; POST: Update the vetted packages of this participant | `3.4` | GET 3.5: description updated; response `400` description updated; POST 3.5: description updated; response `400` description updated | - | - | +| [`/v2/packages`](#path-v2-packages) | GET: Returns the identifiers of all supported packages.; POST: Behaves the same as /dars. This endpoint will be deprecated and removed in a future release. Upload a DAR file to the participant. If vetting is enabled in the request, the DAR is checked for upgrade compatibility with the set of the already vetted packages on the target vetting synchronizer See UploadDarFileRequest for details regarding vetting and the target vetting synchronizer. | `3.4` | GET 3.5: description updated; response `400` description updated; POST 3.5: description updated; response `400` description updated | - | - | +| [`/v2/packages/{package-id}`](#path-v2-packages-package-id) | Returns the contents of a single package. | `3.4` | GET 3.5: description updated; response `400` description updated | - | - | +| [`/v2/packages/{package-id}/status`](#path-v2-packages-package-id-status) | Returns the status of a single package. | `3.4` | GET 3.5: description updated; response `400` description updated | - | - | +| [`/v2/parties`](#path-v2-parties) | GET: List the parties known by the participant. The list returned contains parties whose ledger access is facilitated by the participant and the ones maintained elsewhere.; POST: Allocates a new party on a ledger and adds it to the set managed by the participant. Caller specifies a party identifier suggestion, the actual identifier allocated might be different and is implementation specific. Caller can specify party metadata that is stored locally on the participant. This call may: - Succeed, in which case the actual allocated identifier is visible in the response. - Respond with a gRPC error daml-on-kv-ledger: suggestion's uniqueness is checked by the validators in the consensus layer and call rejected if the identifier is already present. canton: completely different globally unique identifier is allocated. Behind the scenes calls to an internal protocol are made. As that protocol is richer than the surface protocol, the arguments take implicit values The party identifier suggestion must be a valid party name. Party names are required to be non-empty US-ASCII strings built from letters, digits, space, colon, minus and underscore limited to 255 chars | `3.4` | GET 3.5: description updated; response `400` description updated; POST 3.5: description updated; response `400` description updated | - | - | +| [`/v2/parties/external/allocate`](#path-v2-parties-external-allocate) | Alpha 3.3: Endpoint to allocate a new external party on a synchronizer Expected to be stable in 3.5 The external party must be hosted (at least) on this node with either confirmation or observation permissions It can optionally be hosted on other nodes (then called a multi-hosted party). If hosted on additional nodes, explicit authorization of the hosting relationship must be performed on those nodes before the party can be used. Decentralized namespaces are supported but must be provided fully authorized by their owners. The individual owner namespace transactions can be submitted in the same call (fully authorized as well). In the simple case of a non-multi hosted, non-decentralized party, the RPC will return once the party is effectively allocated and ready to use, similarly to the AllocateParty behavior. For more complex scenarios applications may need to query the party status explicitly (only through the admin API as of now). | `3.4` | POST 3.5: description updated; response `400` description updated | - | - | +| [`/v2/parties/external/generate-topology`](#path-v2-parties-external-generate-topology) | Alpha 3.3: Convenience endpoint to generate topology transactions for external signing Expected to be stable in 3.5 You may use this endpoint to generate the common external topology transactions which can be signed externally and uploaded as part of the allocate party process Note that this request will create a normal namespace using the same key for the identity as for signing. More elaborate schemes such as multi-signature or decentralized parties require you to construct the topology transactions yourself. | `3.4` | POST 3.5: description updated; response `400` description updated | - | - | +| [`/v2/parties/participant-id`](#path-v2-parties-participant-id) | Return the identifier of the participant. All horizontally scaled replicas should return the same id. daml-on-kv-ledger: returns an identifier supplied on command line at launch time canton: returns globally unique identifier of the participant | `3.4` | GET 3.5: description updated; response `400` description updated | - | - | +| [`/v2/parties/{party}`](#path-v2-parties-party) | GET: Get the party details of the given parties. Only known parties will be returned in the list.; PATCH: Update selected modifiable participant-local attributes of a party details resource. Can update the participant's local information for local parties. | `3.4` | GET 3.5: description updated; response `400` description updated; PATCH 3.5: description updated; response `400` description updated | - | - | +| [`/v2/state/active-contracts`](#path-v2-state-active-contracts) | Query active contracts list (blocking call). Querying active contracts is an expensive operation and if possible should not be repeated often. Consider querying active contracts initially (for a given offset) and then repeatedly call one of `/v2/updates/...`endpoints to get subsequent modifications. You can also use websockets to get updates with better performance. Returns a stream of the snapshot of the active contracts and incomplete (un)assignments at a ledger offset. Once the stream of GetActiveContractsResponses completes, the client SHOULD begin streaming updates from the update service, starting at the GetActiveContractsRequest.active_at_offset specified in this request. Clients SHOULD NOT assume that the set of active contracts they receive reflects the state at the ledger end. Notice: This endpoint should be used for small results set. When number of results exceeded node configuration limit (`http-list-max-elements-limit`) there will be an error (`413 Content Too Large`) returned. Increasing this limit may lead to performance issues and high memory consumption. Consider using websockets (asyncapi) for better efficiency with larger results. | `3.4` | POST 3.5: description updated; response `400` description updated | - | - | +| [`/v2/state/connected-synchronizers`](#path-v2-state-connected-synchronizers) | Get the list of connected synchronizers at the time of the query. | `3.4` | GET 3.5: description updated; response `400` description updated | - | - | +| [`/v2/state/latest-pruned-offsets`](#path-v2-state-latest-pruned-offsets) | Get the latest successfully pruned ledger offsets | `3.4` | GET 3.5: description updated; response `400` description updated | - | - | +| [`/v2/state/ledger-end`](#path-v2-state-ledger-end) | Get the current ledger end. Subscriptions started with the returned offset will serve events after this RPC was called. | `3.4` | GET 3.5: description updated; response `400` description updated | - | - | +| [`/v2/updates`](#path-v2-updates) | Read the ledger's filtered update stream for the specified contents and filters. It returns the event types in accordance with the stream contents selected. Also the selection criteria for individual events depends on the transaction shape chosen. - ACS delta: a requesting party must be a stakeholder of an event for it to be included. - ledger effects: a requesting party must be a witness of an event for it to be included. Notice: This endpoint should be used for small results set. When number of results exceeded node configuration limit (`http-list-max-elements-limit`) there will be an error (`413 Content Too Large`) returned. Increasing this limit may lead to performance issues and high memory consumption. Consider using websockets (asyncapi) for better efficiency with larger results. | `3.4` | POST 3.5: description updated; response `400` description updated | - | - | +| [`/v2/updates/flats`](#path-v2-updates-flats) | Query flat transactions update list (blocking call). Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use v2/updates instead. Notice: This endpoint should be used for small results set. When number of results exceeded node configuration limit (`http-list-max-elements-limit`) there will be an error (`413 Content Too Large`) returned. Increasing this limit may lead to performance issues and high memory consumption. Consider using websockets (asyncapi) for better efficiency with larger results. | `3.4` | POST 3.5: response `400` description updated | - | - | +| [`/v2/updates/transaction-by-id`](#path-v2-updates-transaction-by-id) | Get transaction by id. Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use v2/updates/update-by-id instead. | `3.4` | POST 3.5: response `400` description updated | - | - | +| [`/v2/updates/transaction-by-offset`](#path-v2-updates-transaction-by-offset) | Get transaction by offset. Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use v2/updates/update-by-offset instead. | `3.4` | POST 3.5: response `400` description updated | - | - | +| [`/v2/updates/transaction-tree-by-id/{update-id}`](#path-v2-updates-transaction-tree-by-id-update-id) | Get transaction tree by id. Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use v2/updates/update-by-id instead. | `3.4` | GET 3.5: response `400` description updated | - | - | +| [`/v2/updates/transaction-tree-by-offset/{offset}`](#path-v2-updates-transaction-tree-by-offset-offset) | Get transaction tree by offset. Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use v2/updates/update-by-offset instead. | `3.4` | GET 3.5: response `400` description updated | - | - | +| [`/v2/updates/trees`](#path-v2-updates-trees) | Query update transactions tree list (blocking call). Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use v2/updates instead. Notice: This endpoint should be used for small results set. When number of results exceeded node configuration limit (`http-list-max-elements-limit`) there will be an error (`413 Content Too Large`) returned. Increasing this limit may lead to performance issues and high memory consumption. Consider using websockets (asyncapi) for better efficiency with larger results. | `3.4` | POST 3.5: response `400` description updated | - | - | +| [`/v2/updates/update-by-id`](#path-v2-updates-update-by-id) | Lookup an update by its ID. If there is no update with this ID, or all the events are filtered, an UPDATE_NOT_FOUND error will be raised. | `3.4` | POST 3.5: description updated; response `400` description updated | - | - | +| [`/v2/updates/update-by-offset`](#path-v2-updates-update-by-offset) | Lookup an update by its offset. If there is no update with this offset, or all the events are filtered, an UPDATE_NOT_FOUND error will be raised. | `3.4` | POST 3.5: description updated; response `400` description updated | - | - | +| [`/v2/users`](#path-v2-users) | GET: List all existing users.; POST: Create a new user. | `3.4` | GET 3.5: description updated; response `400` description updated; POST 3.5: description updated; response `400` description updated | - | - | +| [`/v2/users/{user-id}`](#path-v2-users-user-id) | DELETE: Delete an existing user and all its rights.; GET: Get the user data of a specific user or the authenticated user.; +1 more | `3.4` | DELETE 3.5: description updated; response `400` description updated; GET 3.5: description updated; response `400` description updated; PATCH 3.5: description updated; response `400` description updated | - | - | +| [`/v2/users/{user-id}/identity-provider-id`](#path-v2-users-user-id-identity-provider-id) | Update the assignment of a user from one IDP to another. | `3.4` | PATCH 3.5: description updated; response `400` description updated | - | - | +| [`/v2/users/{user-id}/rights`](#path-v2-users-user-id-rights) | GET: List the set of all rights granted to a user.; PATCH: Revoke rights from a user. Revoking rights does not affect the resource version of the corresponding user.; +1 more | `3.4` | GET 3.5: description updated; response `400` description updated; PATCH 3.5: description updated; response `400` description updated; POST 3.5: description updated; response `400` description updated | - | - | +| [`/v2/version`](#path-v2-version) | Read the Ledger API version | `3.4` | GET 3.5: description updated; response `400` description updated | - | - | ## Endpoint Reference (Latest) + + +### `/livez` + -### `GET /livez` +#### `GET` - Operation ID: `getLivez` - Description: Checks if the service is alive @@ -89,9 +81,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/readyz` + -### `GET /readyz` +#### `GET` - Operation ID: `getReadyz` - Description: Checks if the service is ready to serve requests @@ -104,9 +100,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/authenticated-user` + -### `GET /v2/authenticated-user` +#### `GET` - Operation ID: `getV2Authenticated-user` - Description: Get the user data of the current authenticated user. @@ -125,9 +125,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: query parameter identity-provider-id | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/commands/async/submit` + -### `POST /v2/commands/async/submit` +#### `POST` - Operation ID: `postV2CommandsAsyncSubmit` - Description: Submit a single composite command. @@ -169,9 +173,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/commands/async/submit-reassignment` + -### `POST /v2/commands/async/submit-reassignment` +#### `POST` - Operation ID: `postV2CommandsAsyncSubmit-reassignment` - Description: Submit a single reassignment. @@ -208,9 +216,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/commands/completions` + -### `POST /v2/commands/completions` +#### `POST` - Operation ID: `postV2CommandsCompletions` - Description: Query completions list (blocking call) Subscribe to command completion events. Notice: This endpoint should be used for small results set. When number of results exceeded node configuration limit (`http-list-max-elements-limit`) there will be an error (`413 Content Too Large`) returned. Increasing this limit may lead to performance issues and high memory consumption. Consider using websockets (asyncapi) for better efficiency with larger results. @@ -248,9 +260,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body, Invalid value for: query parameter limit, Invalid value for: query parameter stream_idle_timeout_ms | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/commands/submit-and-wait` + -### `POST /v2/commands/submit-and-wait` +#### `POST` - Operation ID: `postV2CommandsSubmit-and-wait` - Description: Submits a single composite command and waits for its result. Propagates the gRPC error of failed submissions including Daml interpretation errors. @@ -292,9 +308,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/commands/submit-and-wait-for-reassignment` + -### `POST /v2/commands/submit-and-wait-for-reassignment` +#### `POST` - Operation ID: `postV2CommandsSubmit-and-wait-for-reassignment` - Description: Submits a single composite reassignment command, waits for its result, and returns the reassignment. Propagates the gRPC error of failed submission. @@ -331,9 +351,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/commands/submit-and-wait-for-transaction` + -### `POST /v2/commands/submit-and-wait-for-transaction` +#### `POST` - Operation ID: `postV2CommandsSubmit-and-wait-for-transaction` - Description: Submits a single composite command, waits for its result, and returns the transaction. Propagates the gRPC error of failed submissions including Daml interpretation errors. @@ -372,9 +396,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/commands/submit-and-wait-for-transaction-tree` + -### `POST /v2/commands/submit-and-wait-for-transaction-tree` +#### `POST` - Operation ID: `postV2CommandsSubmit-and-wait-for-transaction-tree` - Description: Submit a batch of commands and wait for the transaction trees response. Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use submit-and-wait-for-transaction instead. @@ -416,9 +444,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/contracts/contract-by-id` + -### `POST /v2/contracts/contract-by-id` +#### `POST` - Operation ID: `postV2ContractsContract-by-id` - Description: Looking up contract data by contract ID. This endpoint is experimental / alpha, therefore no backwards compatibility is guaranteed. This endpoint must not be used to look up contracts which entered the participant via party replication or repair service. @@ -447,9 +479,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/dars` + -### `POST /v2/dars` +#### `POST` - Operation ID: `postV2Dars` - Description: Upload a DAR to the participant node @@ -483,9 +519,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body, Invalid value for: query parameter vetAllPackages, Invalid value for: query parameter synchronizerId | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/dars/validate` + -### `POST /v2/dars/validate` +#### `POST` - Operation ID: `postV2DarsValidate` - Description: Validates the DAR and checks the upgrade compatibility of the DAR's packages with the set of the already vetted packages on the target vetting synchronizer. See ValidateDarFileRequest for details regarding the target vetting synchronizer. The operation has no effect on the state of the participant or the Canton ledger: the DAR payload and its packages are not persisted neither are the packages vetted. @@ -518,9 +558,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body, Invalid value for: query parameter synchronizerId | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/events/events-by-contract-id` + -### `POST /v2/events/events-by-contract-id` +#### `POST` - Operation ID: `postV2EventsEvents-by-contract-id` - Description: Get the create and the consuming exercise event for the contract with the provided ID. No events will be returned for contracts that have been pruned because they have already been archived before the latest pruning offset. If the contract cannot be found for the request, or all the contract-events are filtered, a CONTRACT_EVENTS_NOT_FOUND error will be raised. @@ -558,9 +602,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/idps` + -### `GET /v2/idps` +#### `GET` - Operation ID: `getV2Idps` - Description: List all existing identity provider configurations. @@ -575,7 +623,7 @@ Generated from supplied versioned OpenAPI artifacts. -### `POST /v2/idps` +#### `POST` - Operation ID: `postV2Idps` - Description: Create a new identity provider configuration. The request will fail if the maximum allowed number of separate configurations is reached. @@ -608,9 +656,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/idps/{idp-id}` + -### `DELETE /v2/idps/{idp-id}` +#### `DELETE` - Operation ID: `deleteV2IdpsIdp-id` - Description: Delete an existing identity provider configuration. @@ -631,7 +683,7 @@ Generated from supplied versioned OpenAPI artifacts. -### `GET /v2/idps/{idp-id}` +#### `GET` - Operation ID: `getV2IdpsIdp-id` - Description: Get the identity provider configuration data by id. @@ -652,7 +704,7 @@ Generated from supplied versioned OpenAPI artifacts. -### `PATCH /v2/idps/{idp-id}` +#### `PATCH` - Operation ID: `patchV2IdpsIdp-id` - Description: Update selected modifiable attribute of an identity provider config resource described by the ``IdentityProviderConfig`` message. @@ -696,9 +748,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/interactive-submission/execute` + -### `POST /v2/interactive-submission/execute` +#### `POST` - Operation ID: `postV2Interactive-submissionExecute` - Description: Execute a prepared submission _asynchronously_ on the ledger. Requires a signature of the transaction from the submitting external party. @@ -739,9 +795,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/interactive-submission/executeAndWait` + -### `POST /v2/interactive-submission/executeAndWait` +#### `POST` - Operation ID: `postV2Interactive-submissionExecuteandwait` - Description: Similar to ExecuteSubmission but _synchronously_ wait for the completion of the transaction IMPORTANT: Relying on the response from this endpoint requires trusting the Participant Node to be honest. A malicious node could make a successfully committed request appeared failed and vice versa @@ -782,9 +842,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/interactive-submission/executeAndWaitForTransaction` + -### `POST /v2/interactive-submission/executeAndWaitForTransaction` +#### `POST` - Operation ID: `postV2Interactive-submissionExecuteandwaitfortransaction` - Description: Similar to ExecuteSubmissionAndWait but additionally returns the transaction IMPORTANT: Relying on the response from this endpoint requires trusting the Participant Node to be honest. A malicious node could make a successfully committed request appear as failed and vice versa @@ -825,9 +889,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/interactive-submission/preferred-package-version` + -### `GET /v2/interactive-submission/preferred-package-version` +#### `GET` - Operation ID: `getV2Interactive-submissionPreferred-package-version` - Description: A preferred package is the highest-versioned package for a provided package-name that is vetted by all the participants hosting the provided parties. Ledger API clients should use this endpoint for constructing command submissions that are compatible with the provided preferred package, by making informed decisions on: - which are the compatible packages that can be used to create contracts - which contract or exercise choice argument version can be used in the command - which choices can be executed on a template or interface of a contract Can be accessed by any Ledger API client with a valid token when Ledger API authorization is enabled. Provided for backwards compatibility, it will be removed in the Canton version 3.4.0 @@ -849,9 +917,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: query parameter parties, Invalid value for: query parameter package-name, Invalid value for: query parameter vetting_valid_at, Invalid value for: query parameter synchronizer-id | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/interactive-submission/preferred-packages` + -### `POST /v2/interactive-submission/preferred-packages` +#### `POST` - Operation ID: `postV2Interactive-submissionPreferred-packages` - Description: Compute the preferred packages for the vetting requirements in the request. A preferred package is the highest-versioned package for a provided package-name that is vetted by all the participants hosting the provided parties. Ledger API clients should use this endpoint for constructing command submissions that are compatible with the provided preferred packages, by making informed decisions on: - which are the compatible packages that can be used to create contracts - which contract or exercise choice argument version can be used in the command - which choices can be executed on a template or interface of a contract If the package preferences could not be computed due to no selection satisfying the requirements, a `FAILED_PRECONDITION` error will be returned. Can be accessed by any Ledger API client with a valid token when Ledger API authorization is enabled. Experimental API: this endpoint is not guaranteed to provide backwards compatibility in future releases @@ -887,9 +959,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/interactive-submission/prepare` + -### `POST /v2/interactive-submission/prepare` +#### `POST` - Operation ID: `postV2Interactive-submissionPrepare` - Description: Requires `readAs` scope for the submitting party when LAPI User authorization is enabled @@ -931,9 +1007,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/package-vetting` + -### `GET /v2/package-vetting` +#### `GET` - Operation ID: `getV2Package-vetting` - Description: Lists which participant node vetted what packages on which synchronizer. Can be called by any authenticated user. @@ -981,7 +1061,7 @@ Generated from supplied versioned OpenAPI artifacts. -### `POST /v2/package-vetting` +#### `POST` - Operation ID: `postV2Package-vetting` - Description: Update the vetted packages of this participant @@ -1016,9 +1096,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/packages` + -### `GET /v2/packages` +#### `GET` - Operation ID: `getV2Packages` - Description: Returns the identifiers of all supported packages. @@ -1033,7 +1117,7 @@ Generated from supplied versioned OpenAPI artifacts. -### `POST /v2/packages` +#### `POST` - Operation ID: `postV2Packages` - Description: Behaves the same as /dars. This endpoint will be deprecated and removed in a future release. Upload a DAR file to the participant. If vetting is enabled in the request, the DAR is checked for upgrade compatibility with the set of the already vetted packages on the target vetting synchronizer See UploadDarFileRequest for details regarding vetting and the target vetting synchronizer. @@ -1067,9 +1151,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body, Invalid value for: query parameter vetAllPackages, Invalid value for: query parameter synchronizerId | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/packages/{package-id}` + -### `GET /v2/packages/{package-id}` +#### `GET` - Operation ID: `getV2PackagesPackage-id` - Description: Returns the contents of a single package. @@ -1088,9 +1176,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/packages/{package-id}/status` + -### `GET /v2/packages/{package-id}/status` +#### `GET` - Operation ID: `getV2PackagesPackage-idStatus` - Description: Returns the status of a single package. @@ -1109,9 +1201,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/parties` + -### `GET /v2/parties` +#### `GET` - Operation ID: `getV2Parties` - Description: List the parties known by the participant. The list returned contains parties whose ledger access is facilitated by the participant and the ones maintained elsewhere. @@ -1135,7 +1231,7 @@ Generated from supplied versioned OpenAPI artifacts. -### `POST /v2/parties` +#### `POST` - Operation ID: `postV2Parties` - Description: Allocates a new party on a ledger and adds it to the set managed by the participant. Caller specifies a party identifier suggestion, the actual identifier allocated might be different and is implementation specific. Caller can specify party metadata that is stored locally on the participant. This call may: - Succeed, in which case the actual allocated identifier is visible in the response. - Respond with a gRPC error daml-on-kv-ledger: suggestion's uniqueness is checked by the validators in the consensus layer and call rejected if the identifier is already present. canton: completely different globally unique identifier is allocated. Behind the scenes calls to an internal protocol are made. As that protocol is richer than the surface protocol, the arguments take implicit values The party identifier suggestion must be a valid party name. Party names are required to be non-empty US-ASCII strings built from letters, digits, space, colon, minus and underscore limited to 255 chars @@ -1171,9 +1267,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/parties/external/allocate` + -### `POST /v2/parties/external/allocate` +#### `POST` - Operation ID: `postV2PartiesExternalAllocate` - Description: Alpha 3.3: Endpoint to allocate a new external party on a synchronizer Expected to be stable in 3.5 The external party must be hosted (at least) on this node with either confirmation or observation permissions It can optionally be hosted on other nodes (then called a multi-hosted party). If hosted on additional nodes, explicit authorization of the hosting relationship must be performed on those nodes before the party can be used. Decentralized namespaces are supported but must be provided fully authorized by their owners. The individual owner namespace transactions can be submitted in the same call (fully authorized as well). In the simple case of a non-multi hosted, non-decentralized party, the RPC will return once the party is effectively allocated and ready to use, similarly to the AllocateParty behavior. For more complex scenarios applications may need to query the party status explicitly (only through the admin API as of now). @@ -1207,9 +1307,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/parties/external/generate-topology` + -### `POST /v2/parties/external/generate-topology` +#### `POST` - Operation ID: `postV2PartiesExternalGenerate-topology` - Description: Alpha 3.3: Convenience endpoint to generate topology transactions for external signing Expected to be stable in 3.5 You may use this endpoint to generate the common external topology transactions which can be signed externally and uploaded as part of the allocate party process Note that this request will create a normal namespace using the same key for the identity as for signing. More elaborate schemes such as multi-signature or decentralized parties require you to construct the topology transactions yourself. @@ -1244,9 +1348,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/parties/participant-id` + -### `GET /v2/parties/participant-id` +#### `GET` - Operation ID: `getV2PartiesParticipant-id` - Description: Return the identifier of the participant. All horizontally scaled replicas should return the same id. daml-on-kv-ledger: returns an identifier supplied on command line at launch time canton: returns globally unique identifier of the participant @@ -1259,9 +1367,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/parties/{party}` + -### `GET /v2/parties/{party}` +#### `GET` - Operation ID: `getV2PartiesParty` - Description: Get the party details of the given parties. Only known parties will be returned in the list. @@ -1284,7 +1396,7 @@ Generated from supplied versioned OpenAPI artifacts. -### `PATCH /v2/parties/{party}` +#### `PATCH` - Operation ID: `patchV2PartiesParty` - Description: Update selected modifiable participant-local attributes of a party details resource. Can update the participant's local information for local parties. @@ -1326,9 +1438,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/state/active-contracts` + -### `POST /v2/state/active-contracts` +#### `POST` - Operation ID: `postV2StateActive-contracts` - Description: Query active contracts list (blocking call). Querying active contracts is an expensive operation and if possible should not be repeated often. Consider querying active contracts initially (for a given offset) and then repeatedly call one of `/v2/updates/...`endpoints to get subsequent modifications. You can also use websockets to get updates with better performance. Returns a stream of the snapshot of the active contracts and incomplete (un)assignments at a ledger offset. Once the stream of GetActiveContractsResponses completes, the client SHOULD begin streaming updates from the update service, starting at the GetActiveContractsRequest.active_at_offset specified in this request. Clients SHOULD NOT assume that the set of active contracts they receive reflects the state at the ledger end. Notice: This endpoint should be used for small results set. When number of results exceeded node configuration limit (`http-list-max-elements-limit`) there will be an error (`413 Content Too Large`) returned. Increasing this limit may lead to performance issues and high memory consumption. Consider using websockets (asyncapi) for better efficiency with larger results. @@ -1364,9 +1480,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body, Invalid value for: query parameter limit, Invalid value for: query parameter stream_idle_timeout_ms | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/state/connected-synchronizers` + -### `GET /v2/state/connected-synchronizers` +#### `GET` - Operation ID: `getV2StateConnected-synchronizers` - Description: Get the list of connected synchronizers at the time of the query. @@ -1387,9 +1507,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: query parameter party, Invalid value for: query parameter participantId, Invalid value for: query parameter identityProviderId | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/state/latest-pruned-offsets` + -### `GET /v2/state/latest-pruned-offsets` +#### `GET` - Operation ID: `getV2StateLatest-pruned-offsets` - Description: Get the latest successfully pruned ledger offsets @@ -1402,9 +1526,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/state/ledger-end` + -### `GET /v2/state/ledger-end` +#### `GET` - Operation ID: `getV2StateLedger-end` - Description: Get the current ledger end. Subscriptions started with the returned offset will serve events after this RPC was called. @@ -1417,9 +1545,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/updates` + -### `POST /v2/updates` +#### `POST` - Operation ID: `postV2Updates` - Description: Read the ledger's filtered update stream for the specified contents and filters. It returns the event types in accordance with the stream contents selected. Also the selection criteria for individual events depends on the transaction shape chosen. - ACS delta: a requesting party must be a stakeholder of an event for it to be included. - ledger effects: a requesting party must be a witness of an event for it to be included. Notice: This endpoint should be used for small results set. When number of results exceeded node configuration limit (`http-list-max-elements-limit`) there will be an error (`413 Content Too Large`) returned. Increasing this limit may lead to performance issues and high memory consumption. Consider using websockets (asyncapi) for better efficiency with larger results. @@ -1491,9 +1623,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body, Invalid value for: query parameter limit, Invalid value for: query parameter stream_idle_timeout_ms | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/updates/flats` + -### `POST /v2/updates/flats` +#### `POST` - Operation ID: `postV2UpdatesFlats` - Description: Query flat transactions update list (blocking call). Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use v2/updates instead. Notice: This endpoint should be used for small results set. When number of results exceeded node configuration limit (`http-list-max-elements-limit`) there will be an error (`413 Content Too Large`) returned. Increasing this limit may lead to performance issues and high memory consumption. Consider using websockets (asyncapi) for better efficiency with larger results. @@ -1565,9 +1701,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body, Invalid value for: query parameter limit, Invalid value for: query parameter stream_idle_timeout_ms | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/updates/transaction-by-id` + -### `POST /v2/updates/transaction-by-id` +#### `POST` - Operation ID: `postV2UpdatesTransaction-by-id` - Description: Get transaction by id. Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use v2/updates/update-by-id instead. @@ -1596,9 +1736,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/updates/transaction-by-offset` + -### `POST /v2/updates/transaction-by-offset` +#### `POST` - Operation ID: `postV2UpdatesTransaction-by-offset` - Description: Get transaction by offset. Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use v2/updates/update-by-offset instead. @@ -1627,9 +1771,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/updates/transaction-tree-by-id/{update-id}` + -### `GET /v2/updates/transaction-tree-by-id/{update-id}` +#### `GET` - Operation ID: `getV2UpdatesTransaction-tree-by-idUpdate-id` - Description: Get transaction tree by id. Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use v2/updates/update-by-id instead. @@ -1649,9 +1797,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: query parameter parties | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/updates/transaction-tree-by-offset/{offset}` + -### `GET /v2/updates/transaction-tree-by-offset/{offset}` +#### `GET` - Operation ID: `getV2UpdatesTransaction-tree-by-offsetOffset` - Description: Get transaction tree by offset. Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use v2/updates/update-by-offset instead. @@ -1671,9 +1823,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: path parameter offset, Invalid value for: query parameter parties | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/updates/trees` + -### `POST /v2/updates/trees` +#### `POST` - Operation ID: `postV2UpdatesTrees` - Description: Query update transactions tree list (blocking call). Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use v2/updates instead. Notice: This endpoint should be used for small results set. When number of results exceeded node configuration limit (`http-list-max-elements-limit`) there will be an error (`413 Content Too Large`) returned. Increasing this limit may lead to performance issues and high memory consumption. Consider using websockets (asyncapi) for better efficiency with larger results. @@ -1745,9 +1901,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body, Invalid value for: query parameter limit, Invalid value for: query parameter stream_idle_timeout_ms | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/updates/update-by-id` + -### `POST /v2/updates/update-by-id` +#### `POST` - Operation ID: `postV2UpdatesUpdate-by-id` - Description: Lookup an update by its ID. If there is no update with this ID, or all the events are filtered, an UPDATE_NOT_FOUND error will be raised. @@ -1802,9 +1962,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/updates/update-by-offset` + -### `POST /v2/updates/update-by-offset` +#### `POST` - Operation ID: `postV2UpdatesUpdate-by-offset` - Description: Lookup an update by its offset. If there is no update with this offset, or all the events are filtered, an UPDATE_NOT_FOUND error will be raised. @@ -1859,9 +2023,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/users` + -### `GET /v2/users` +#### `GET` - Operation ID: `getV2Users` - Description: List all existing users. @@ -1883,7 +2051,7 @@ Generated from supplied versioned OpenAPI artifacts. -### `POST /v2/users` +#### `POST` - Operation ID: `postV2Users` - Description: Create a new user. @@ -1914,9 +2082,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/users/{user-id}` + -### `DELETE /v2/users/{user-id}` +#### `DELETE` - Operation ID: `deleteV2UsersUser-id` - Description: Delete an existing user and all its rights. @@ -1937,7 +2109,7 @@ Generated from supplied versioned OpenAPI artifacts. -### `GET /v2/users/{user-id}` +#### `GET` - Operation ID: `getV2UsersUser-id` - Description: Get the user data of a specific user or the authenticated user. @@ -1959,7 +2131,7 @@ Generated from supplied versioned OpenAPI artifacts. -### `PATCH /v2/users/{user-id}` +#### `PATCH` - Operation ID: `patchV2UsersUser-id` - Description: Update selected modifiable attribute of a user resource described by the ``User`` message. @@ -2001,9 +2173,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/users/{user-id}/identity-provider-id` + -### `PATCH /v2/users/{user-id}/identity-provider-id` +#### `PATCH` - Operation ID: `patchV2UsersUser-idIdentity-provider-id` - Description: Update the assignment of a user from one IDP to another. @@ -2038,9 +2214,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/users/{user-id}/rights` + -### `GET /v2/users/{user-id}/rights` +#### `GET` - Operation ID: `getV2UsersUser-idRights` - Description: List the set of all rights granted to a user. @@ -2061,7 +2241,7 @@ Generated from supplied versioned OpenAPI artifacts. -### `PATCH /v2/users/{user-id}/rights` +#### `PATCH` - Operation ID: `patchV2UsersUser-idRights` - Description: Revoke rights from a user. Revoking rights does not affect the resource version of the corresponding user. @@ -2098,7 +2278,7 @@ Generated from supplied versioned OpenAPI artifacts. -### `POST /v2/users/{user-id}/rights` +#### `POST` - Operation ID: `postV2UsersUser-idRights` - Description: Grant rights to a user. Granting rights does not affect the resource version of the corresponding user. @@ -2133,9 +2313,13 @@ Generated from supplied versioned OpenAPI artifacts. | `400` | Invalid value, Invalid value for: body | `text/plain` | `text/plain:string` | | `default` | - | `application/json` | `application/json:object` | + + +### `/v2/version` + -### `GET /v2/version` +#### `GET` - Operation ID: `getV2Version` - Description: Read the Ledger API version diff --git a/tests/test_openapi.py b/tests/test_openapi.py index 6640cc5..5fc6156 100644 --- a/tests/test_openapi.py +++ b/tests/test_openapi.py @@ -262,9 +262,10 @@ def test_render_pages_from_report_round_trip(self) -> None: self.assertIn("Version Change Timeline", spec_page) self.assertIn("Table of Contents", spec_page) self.assertIn("| Name | Summary | Introduced | Changed | Deprecated | Removed |", spec_page) - self.assertIn("[`GET /ping`](#endpoint-get-ping)", spec_page) + self.assertIn("[`/ping`](#path-ping)", spec_page) + self.assertIn('', spec_page) self.assertIn('', spec_page) - self.assertIn("| [`GET /ping`](#endpoint-get-ping) | Ping endpoint | `v0.1.0` | v0.1.1:", spec_page) + self.assertIn("| [`/ping`](#path-ping) | Ping endpoint | `v0.1.0` | GET v0.1.1:", spec_page) self.assertIn("summary changed `Ping` -> `Ping endpoint`", spec_page) self.assertIn("query param `limit` added", spec_page) self.assertIn("response `200` description updated", spec_page) @@ -273,9 +274,59 @@ def test_render_pages_from_report_round_trip(self) -> None: self.assertGreater(spec_page.index("Spec Metadata"), spec_page.index("Latest Components")) self.assertGreater(spec_page.index("Entity Summary"), spec_page.index("Spec Metadata")) self.assertIn("Endpoint Reference (Latest)", spec_page) - self.assertIn("### `GET /ping`", spec_page) + self.assertIn("### `/ping`", spec_page) + self.assertIn("#### `GET`", spec_page) + self.assertNotIn("### `GET /ping`", spec_page) self.assertNotIn("| Endpoint | Operation ID | Summary | Tags |", spec_page) + def test_render_pages_group_table_of_contents_and_reference_by_path(self) -> None: + report = build_openapi_lifecycle_report_from_snapshots( + [ + self._snapshot( + "v0.1.0", + "published/utility.yaml", + """ + openapi: 3.0.3 + info: + title: Utility API + version: 0.1.0 + paths: + /widgets: + get: + operationId: listWidgets + summary: List widgets + responses: + "200": + description: ok + post: + operationId: createWidget + summary: Create widget + responses: + "200": + description: ok + """, + ) + ], + self._config(), + source_name="unit test snapshots", + version_filter="unit test versions", + ) + + pages = build_pages(report) + out_dir = self.root / "out-grouped-by-path" + write_pages(pages, out_dir) + spec_page = (out_dir / "specs" / "utility-yaml.mdx").read_text(encoding="utf-8") + + self.assertIn("[`/widgets`](#path-widgets)", spec_page) + self.assertIn("| [`/widgets`](#path-widgets) | GET: List widgets; POST: Create widget | `v0.1.0` | - | - | - |", spec_page) + self.assertNotIn("[`GET /widgets`](#endpoint-get-widgets)", spec_page) + self.assertNotIn("[`POST /widgets`](#endpoint-post-widgets)", spec_page) + self.assertIn("### `/widgets`", spec_page) + self.assertIn("#### `GET`", spec_page) + self.assertIn("#### `POST`", spec_page) + self.assertIn('', spec_page) + self.assertIn('', spec_page) + def test_render_pages_show_required_request_body_fields(self) -> None: report = build_openapi_lifecycle_report_from_snapshots( [ @@ -334,7 +385,8 @@ def test_render_pages_show_required_request_body_fields(self) -> None: write_pages(pages, out_dir) spec_page = (out_dir / "specs" / "utility-yaml.mdx").read_text(encoding="utf-8") - self.assertIn("### `POST /submit`", spec_page) + self.assertIn("### `/submit`", spec_page) + self.assertIn("#### `POST`", spec_page) self.assertIn("| Content Type | Schema | Required Fields |", spec_page) self.assertIn("| `application/json` | `object` | `commandId`, `payload` |", spec_page) self.assertIn("**Request Example: `application/json`**", spec_page) @@ -375,7 +427,9 @@ def test_render_pages_keep_openapi_path_placeholders_readable(self) -> None: write_pages(pages, out_dir) spec_page = (out_dir / "specs" / "utility-yaml.mdx").read_text(encoding="utf-8") - self.assertIn("`GET /items/{itemId}`", spec_page) + self.assertIn("[`/items/{itemId}`](#path-items-itemid)", spec_page) + self.assertIn("### `/items/{itemId}`", spec_page) + self.assertIn("#### `GET`", spec_page) self.assertIn("Fetch \\{itemId\\}", spec_page) self.assertIn("Get \\{itemId\\} by id.", spec_page) self.assertNotIn("{", spec_page) diff --git a/tests/test_openapi_published_fixtures.py b/tests/test_openapi_published_fixtures.py index 65d41f6..5dd59f5 100644 --- a/tests/test_openapi_published_fixtures.py +++ b/tests/test_openapi_published_fixtures.py @@ -82,6 +82,9 @@ def test_cli_build_api_pages_from_manifest_writes_mdx_pages(self) -> None: spec_page = (output_dir / "specs" / "json-ledger-api-openapi-yaml.mdx").read_text(encoding="utf-8") self.assertIn("Table of Contents", spec_page) self.assertIn("| Name | Summary | Introduced | Changed | Deprecated | Removed |", spec_page) + self.assertIn("[`/livez`](#path-livez)", spec_page) + self.assertIn("### `/livez`", spec_page) + self.assertIn("#### `GET`", spec_page) self.assertIn("| Content Type | Schema | Required Fields |", spec_page) self.assertIn("| `application/json` | `object` | `actAs`, `commandId`, `commands` |", spec_page) self.assertIn("**Request Example: `application/json`**", spec_page) From 13a208757db742edc4c225a6f4c86e930623f73c Mon Sep 17 00:00:00 2001 From: danielporterda Date: Wed, 8 Apr 2026 15:57:37 -0400 Subject: [PATCH 2/2] Hide single-verb OpenAPI method headings --- src/x2mdx/openapi/render.py | 1 + .../openapi/endpoint_reference.md.j2 | 4 + .../openapi/expected/json-api-reference.mdx | 80 +++++++++---------- tests/test_openapi.py | 9 ++- tests/test_openapi_published_fixtures.py | 2 +- 5 files changed, 52 insertions(+), 44 deletions(-) diff --git a/src/x2mdx/openapi/render.py b/src/x2mdx/openapi/render.py index 1472445..66d4dec 100644 --- a/src/x2mdx/openapi/render.py +++ b/src/x2mdx/openapi/render.py @@ -477,6 +477,7 @@ def render_endpoint_reference(spec: OpenApiSpecLifecycle, operations: list[dict[ { "anchor_id": str(group["path_anchor_id"]), "header": md_code(str(group["path"])), + "show_method_headings": len(group["operations"]) > 1, "operations": [_endpoint_reference_operation(item["operation"]) for item in group["operations"]], } for group in _latest_operation_groups(spec, operations[:max_endpoints]) diff --git a/src/x2mdx/templates/openapi/endpoint_reference.md.j2 b/src/x2mdx/templates/openapi/endpoint_reference.md.j2 index 65105d9..8675962 100644 --- a/src/x2mdx/templates/openapi/endpoint_reference.md.j2 +++ b/src/x2mdx/templates/openapi/endpoint_reference.md.j2 @@ -5,7 +5,11 @@ {% for operation in path_group.operations %} {{ anchor(operation.anchor_id) }} +{% if path_group.show_method_headings %} {{ heading(4, operation.header) }} +{% else %} +{{ paragraph("**Method:** " ~ operation.header) }} +{% endif %} {% if operation.bullet_items %} {{ bullet_list(operation.bullet_items) }} {% endif %} diff --git a/tests/fixtures/characterization/openapi/expected/json-api-reference.mdx b/tests/fixtures/characterization/openapi/expected/json-api-reference.mdx index 78282fa..09a6de2 100644 --- a/tests/fixtures/characterization/openapi/expected/json-api-reference.mdx +++ b/tests/fixtures/characterization/openapi/expected/json-api-reference.mdx @@ -68,7 +68,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `GET` +**Method:** `GET` - Operation ID: `getLivez` - Description: Checks if the service is alive @@ -87,7 +87,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `GET` +**Method:** `GET` - Operation ID: `getReadyz` - Description: Checks if the service is ready to serve requests @@ -106,7 +106,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `GET` +**Method:** `GET` - Operation ID: `getV2Authenticated-user` - Description: Get the user data of the current authenticated user. @@ -131,7 +131,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `POST` +**Method:** `POST` - Operation ID: `postV2CommandsAsyncSubmit` - Description: Submit a single composite command. @@ -179,7 +179,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `POST` +**Method:** `POST` - Operation ID: `postV2CommandsAsyncSubmit-reassignment` - Description: Submit a single reassignment. @@ -222,7 +222,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `POST` +**Method:** `POST` - Operation ID: `postV2CommandsCompletions` - Description: Query completions list (blocking call) Subscribe to command completion events. Notice: This endpoint should be used for small results set. When number of results exceeded node configuration limit (`http-list-max-elements-limit`) there will be an error (`413 Content Too Large`) returned. Increasing this limit may lead to performance issues and high memory consumption. Consider using websockets (asyncapi) for better efficiency with larger results. @@ -266,7 +266,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `POST` +**Method:** `POST` - Operation ID: `postV2CommandsSubmit-and-wait` - Description: Submits a single composite command and waits for its result. Propagates the gRPC error of failed submissions including Daml interpretation errors. @@ -314,7 +314,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `POST` +**Method:** `POST` - Operation ID: `postV2CommandsSubmit-and-wait-for-reassignment` - Description: Submits a single composite reassignment command, waits for its result, and returns the reassignment. Propagates the gRPC error of failed submission. @@ -357,7 +357,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `POST` +**Method:** `POST` - Operation ID: `postV2CommandsSubmit-and-wait-for-transaction` - Description: Submits a single composite command, waits for its result, and returns the transaction. Propagates the gRPC error of failed submissions including Daml interpretation errors. @@ -402,7 +402,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `POST` +**Method:** `POST` - Operation ID: `postV2CommandsSubmit-and-wait-for-transaction-tree` - Description: Submit a batch of commands and wait for the transaction trees response. Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use submit-and-wait-for-transaction instead. @@ -450,7 +450,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `POST` +**Method:** `POST` - Operation ID: `postV2ContractsContract-by-id` - Description: Looking up contract data by contract ID. This endpoint is experimental / alpha, therefore no backwards compatibility is guaranteed. This endpoint must not be used to look up contracts which entered the participant via party replication or repair service. @@ -485,7 +485,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `POST` +**Method:** `POST` - Operation ID: `postV2Dars` - Description: Upload a DAR to the participant node @@ -525,7 +525,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `POST` +**Method:** `POST` - Operation ID: `postV2DarsValidate` - Description: Validates the DAR and checks the upgrade compatibility of the DAR's packages with the set of the already vetted packages on the target vetting synchronizer. See ValidateDarFileRequest for details regarding the target vetting synchronizer. The operation has no effect on the state of the participant or the Canton ledger: the DAR payload and its packages are not persisted neither are the packages vetted. @@ -564,7 +564,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `POST` +**Method:** `POST` - Operation ID: `postV2EventsEvents-by-contract-id` - Description: Get the create and the consuming exercise event for the contract with the provided ID. No events will be returned for contracts that have been pruned because they have already been archived before the latest pruning offset. If the contract cannot be found for the request, or all the contract-events are filtered, a CONTRACT_EVENTS_NOT_FOUND error will be raised. @@ -754,7 +754,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `POST` +**Method:** `POST` - Operation ID: `postV2Interactive-submissionExecute` - Description: Execute a prepared submission _asynchronously_ on the ledger. Requires a signature of the transaction from the submitting external party. @@ -801,7 +801,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `POST` +**Method:** `POST` - Operation ID: `postV2Interactive-submissionExecuteandwait` - Description: Similar to ExecuteSubmission but _synchronously_ wait for the completion of the transaction IMPORTANT: Relying on the response from this endpoint requires trusting the Participant Node to be honest. A malicious node could make a successfully committed request appeared failed and vice versa @@ -848,7 +848,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `POST` +**Method:** `POST` - Operation ID: `postV2Interactive-submissionExecuteandwaitfortransaction` - Description: Similar to ExecuteSubmissionAndWait but additionally returns the transaction IMPORTANT: Relying on the response from this endpoint requires trusting the Participant Node to be honest. A malicious node could make a successfully committed request appear as failed and vice versa @@ -895,7 +895,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `GET` +**Method:** `GET` - Operation ID: `getV2Interactive-submissionPreferred-package-version` - Description: A preferred package is the highest-versioned package for a provided package-name that is vetted by all the participants hosting the provided parties. Ledger API clients should use this endpoint for constructing command submissions that are compatible with the provided preferred package, by making informed decisions on: - which are the compatible packages that can be used to create contracts - which contract or exercise choice argument version can be used in the command - which choices can be executed on a template or interface of a contract Can be accessed by any Ledger API client with a valid token when Ledger API authorization is enabled. Provided for backwards compatibility, it will be removed in the Canton version 3.4.0 @@ -923,7 +923,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `POST` +**Method:** `POST` - Operation ID: `postV2Interactive-submissionPreferred-packages` - Description: Compute the preferred packages for the vetting requirements in the request. A preferred package is the highest-versioned package for a provided package-name that is vetted by all the participants hosting the provided parties. Ledger API clients should use this endpoint for constructing command submissions that are compatible with the provided preferred packages, by making informed decisions on: - which are the compatible packages that can be used to create contracts - which contract or exercise choice argument version can be used in the command - which choices can be executed on a template or interface of a contract If the package preferences could not be computed due to no selection satisfying the requirements, a `FAILED_PRECONDITION` error will be returned. Can be accessed by any Ledger API client with a valid token when Ledger API authorization is enabled. Experimental API: this endpoint is not guaranteed to provide backwards compatibility in future releases @@ -965,7 +965,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `POST` +**Method:** `POST` - Operation ID: `postV2Interactive-submissionPrepare` - Description: Requires `readAs` scope for the submitting party when LAPI User authorization is enabled @@ -1157,7 +1157,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `GET` +**Method:** `GET` - Operation ID: `getV2PackagesPackage-id` - Description: Returns the contents of a single package. @@ -1182,7 +1182,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `GET` +**Method:** `GET` - Operation ID: `getV2PackagesPackage-idStatus` - Description: Returns the status of a single package. @@ -1273,7 +1273,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `POST` +**Method:** `POST` - Operation ID: `postV2PartiesExternalAllocate` - Description: Alpha 3.3: Endpoint to allocate a new external party on a synchronizer Expected to be stable in 3.5 The external party must be hosted (at least) on this node with either confirmation or observation permissions It can optionally be hosted on other nodes (then called a multi-hosted party). If hosted on additional nodes, explicit authorization of the hosting relationship must be performed on those nodes before the party can be used. Decentralized namespaces are supported but must be provided fully authorized by their owners. The individual owner namespace transactions can be submitted in the same call (fully authorized as well). In the simple case of a non-multi hosted, non-decentralized party, the RPC will return once the party is effectively allocated and ready to use, similarly to the AllocateParty behavior. For more complex scenarios applications may need to query the party status explicitly (only through the admin API as of now). @@ -1313,7 +1313,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `POST` +**Method:** `POST` - Operation ID: `postV2PartiesExternalGenerate-topology` - Description: Alpha 3.3: Convenience endpoint to generate topology transactions for external signing Expected to be stable in 3.5 You may use this endpoint to generate the common external topology transactions which can be signed externally and uploaded as part of the allocate party process Note that this request will create a normal namespace using the same key for the identity as for signing. More elaborate schemes such as multi-signature or decentralized parties require you to construct the topology transactions yourself. @@ -1354,7 +1354,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `GET` +**Method:** `GET` - Operation ID: `getV2PartiesParticipant-id` - Description: Return the identifier of the participant. All horizontally scaled replicas should return the same id. daml-on-kv-ledger: returns an identifier supplied on command line at launch time canton: returns globally unique identifier of the participant @@ -1444,7 +1444,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `POST` +**Method:** `POST` - Operation ID: `postV2StateActive-contracts` - Description: Query active contracts list (blocking call). Querying active contracts is an expensive operation and if possible should not be repeated often. Consider querying active contracts initially (for a given offset) and then repeatedly call one of `/v2/updates/...`endpoints to get subsequent modifications. You can also use websockets to get updates with better performance. Returns a stream of the snapshot of the active contracts and incomplete (un)assignments at a ledger offset. Once the stream of GetActiveContractsResponses completes, the client SHOULD begin streaming updates from the update service, starting at the GetActiveContractsRequest.active_at_offset specified in this request. Clients SHOULD NOT assume that the set of active contracts they receive reflects the state at the ledger end. Notice: This endpoint should be used for small results set. When number of results exceeded node configuration limit (`http-list-max-elements-limit`) there will be an error (`413 Content Too Large`) returned. Increasing this limit may lead to performance issues and high memory consumption. Consider using websockets (asyncapi) for better efficiency with larger results. @@ -1486,7 +1486,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `GET` +**Method:** `GET` - Operation ID: `getV2StateConnected-synchronizers` - Description: Get the list of connected synchronizers at the time of the query. @@ -1513,7 +1513,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `GET` +**Method:** `GET` - Operation ID: `getV2StateLatest-pruned-offsets` - Description: Get the latest successfully pruned ledger offsets @@ -1532,7 +1532,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `GET` +**Method:** `GET` - Operation ID: `getV2StateLedger-end` - Description: Get the current ledger end. Subscriptions started with the returned offset will serve events after this RPC was called. @@ -1551,7 +1551,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `POST` +**Method:** `POST` - Operation ID: `postV2Updates` - Description: Read the ledger's filtered update stream for the specified contents and filters. It returns the event types in accordance with the stream contents selected. Also the selection criteria for individual events depends on the transaction shape chosen. - ACS delta: a requesting party must be a stakeholder of an event for it to be included. - ledger effects: a requesting party must be a witness of an event for it to be included. Notice: This endpoint should be used for small results set. When number of results exceeded node configuration limit (`http-list-max-elements-limit`) there will be an error (`413 Content Too Large`) returned. Increasing this limit may lead to performance issues and high memory consumption. Consider using websockets (asyncapi) for better efficiency with larger results. @@ -1629,7 +1629,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `POST` +**Method:** `POST` - Operation ID: `postV2UpdatesFlats` - Description: Query flat transactions update list (blocking call). Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use v2/updates instead. Notice: This endpoint should be used for small results set. When number of results exceeded node configuration limit (`http-list-max-elements-limit`) there will be an error (`413 Content Too Large`) returned. Increasing this limit may lead to performance issues and high memory consumption. Consider using websockets (asyncapi) for better efficiency with larger results. @@ -1707,7 +1707,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `POST` +**Method:** `POST` - Operation ID: `postV2UpdatesTransaction-by-id` - Description: Get transaction by id. Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use v2/updates/update-by-id instead. @@ -1742,7 +1742,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `POST` +**Method:** `POST` - Operation ID: `postV2UpdatesTransaction-by-offset` - Description: Get transaction by offset. Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use v2/updates/update-by-offset instead. @@ -1777,7 +1777,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `GET` +**Method:** `GET` - Operation ID: `getV2UpdatesTransaction-tree-by-idUpdate-id` - Description: Get transaction tree by id. Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use v2/updates/update-by-id instead. @@ -1803,7 +1803,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `GET` +**Method:** `GET` - Operation ID: `getV2UpdatesTransaction-tree-by-offsetOffset` - Description: Get transaction tree by offset. Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use v2/updates/update-by-offset instead. @@ -1829,7 +1829,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `POST` +**Method:** `POST` - Operation ID: `postV2UpdatesTrees` - Description: Query update transactions tree list (blocking call). Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use v2/updates instead. Notice: This endpoint should be used for small results set. When number of results exceeded node configuration limit (`http-list-max-elements-limit`) there will be an error (`413 Content Too Large`) returned. Increasing this limit may lead to performance issues and high memory consumption. Consider using websockets (asyncapi) for better efficiency with larger results. @@ -1907,7 +1907,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `POST` +**Method:** `POST` - Operation ID: `postV2UpdatesUpdate-by-id` - Description: Lookup an update by its ID. If there is no update with this ID, or all the events are filtered, an UPDATE_NOT_FOUND error will be raised. @@ -1968,7 +1968,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `POST` +**Method:** `POST` - Operation ID: `postV2UpdatesUpdate-by-offset` - Description: Lookup an update by its offset. If there is no update with this offset, or all the events are filtered, an UPDATE_NOT_FOUND error will be raised. @@ -2179,7 +2179,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `PATCH` +**Method:** `PATCH` - Operation ID: `patchV2UsersUser-idIdentity-provider-id` - Description: Update the assignment of a user from one IDP to another. @@ -2319,7 +2319,7 @@ Generated from supplied versioned OpenAPI artifacts. -#### `GET` +**Method:** `GET` - Operation ID: `getV2Version` - Description: Read the Ledger API version diff --git a/tests/test_openapi.py b/tests/test_openapi.py index 5fc6156..5085199 100644 --- a/tests/test_openapi.py +++ b/tests/test_openapi.py @@ -275,7 +275,8 @@ def test_render_pages_from_report_round_trip(self) -> None: self.assertGreater(spec_page.index("Entity Summary"), spec_page.index("Spec Metadata")) self.assertIn("Endpoint Reference (Latest)", spec_page) self.assertIn("### `/ping`", spec_page) - self.assertIn("#### `GET`", spec_page) + self.assertIn("**Method:** `GET`", spec_page) + self.assertNotIn("#### `GET`", spec_page) self.assertNotIn("### `GET /ping`", spec_page) self.assertNotIn("| Endpoint | Operation ID | Summary | Tags |", spec_page) @@ -386,7 +387,8 @@ def test_render_pages_show_required_request_body_fields(self) -> None: spec_page = (out_dir / "specs" / "utility-yaml.mdx").read_text(encoding="utf-8") self.assertIn("### `/submit`", spec_page) - self.assertIn("#### `POST`", spec_page) + self.assertIn("**Method:** `POST`", spec_page) + self.assertNotIn("#### `POST`", spec_page) self.assertIn("| Content Type | Schema | Required Fields |", spec_page) self.assertIn("| `application/json` | `object` | `commandId`, `payload` |", spec_page) self.assertIn("**Request Example: `application/json`**", spec_page) @@ -429,7 +431,8 @@ def test_render_pages_keep_openapi_path_placeholders_readable(self) -> None: self.assertIn("[`/items/{itemId}`](#path-items-itemid)", spec_page) self.assertIn("### `/items/{itemId}`", spec_page) - self.assertIn("#### `GET`", spec_page) + self.assertIn("**Method:** `GET`", spec_page) + self.assertNotIn("#### `GET`", spec_page) self.assertIn("Fetch \\{itemId\\}", spec_page) self.assertIn("Get \\{itemId\\} by id.", spec_page) self.assertNotIn("{", spec_page) diff --git a/tests/test_openapi_published_fixtures.py b/tests/test_openapi_published_fixtures.py index 5dd59f5..6636d33 100644 --- a/tests/test_openapi_published_fixtures.py +++ b/tests/test_openapi_published_fixtures.py @@ -84,7 +84,7 @@ def test_cli_build_api_pages_from_manifest_writes_mdx_pages(self) -> None: self.assertIn("| Name | Summary | Introduced | Changed | Deprecated | Removed |", spec_page) self.assertIn("[`/livez`](#path-livez)", spec_page) self.assertIn("### `/livez`", spec_page) - self.assertIn("#### `GET`", spec_page) + self.assertIn("**Method:** `GET`", spec_page) self.assertIn("| Content Type | Schema | Required Fields |", spec_page) self.assertIn("| `application/json` | `object` | `actAs`, `commandId`, `commands` |", spec_page) self.assertIn("**Request Example: `application/json`**", spec_page)