Conventions

Follow these conventions to keep the API catalogue consistent, to make client generation predictable, and to support multiple simultaneous API versions when breaking changes occur.

OperationId naming rules

Use PascalCase and a clear suffix to indicate intent and version.

Query operations

Pattern: <Verb><Resource><Qualifier>QueryV<MAJOR>

Example: GetCurrentIdentityUserQueryV1

Even when OpenAPI exposes the operation as PATCH for tooling compatibility, the operation name should convey that this is a read/query operation.

Command operations

Pattern: <Verb><Resource><Qualifier>CommandV<MAJOR>

Example: CreateFullAccountCommandV1

Version number in OperationId: append a major version only, for example V1, to the operationId. Minor and patch bumps do not change the operationId.

Response type naming rules

Each operation has a single response type name derived from the operationId by appending Response.

Operation GetCurrentIdentityUserQueryV1 -> GetCurrentIdentityUserQueryV1Response

Operation CreateFullAccountCommandV1 -> CreateFullAccountCommandV1Response

Response schema names should be stored in components/schemas in OpenAPI using the response type name.

Currently in beta only the version v1 will be used and might have breaking changes.

Path versioning

Place the version at the end of the path segment for clarity and routing simplicity. Use the major version only in the path, for example v1 or v2.

QUERY/PATCH query-style path: /identity/current/v1

Command-style path: /accounts/v1

Currently in beta only the version v1 will be used and might have breaking changes.

Multiple versions and coexistence

  • Some endpoints will have multiple published versions, for example v1 and v2, when breaking changes are introduced.
  • Deploy a new major version on /.../vN while leaving the older version active on /.../v(N-1).
  • New clients should target the latest stable major version.
  • Existing clients remain supported for a deprecation window.

Currently in beta only the version v1 will be used and might have breaking changes.

Query endpoints with request bodies

Read-style operations that need a JSON request body are query endpoints. Bridflow accepts the custom QUERY HTTP method for these calls. For OpenAPI compatibility, the same endpoints are still registered and documented in the generated API reference as PATCH.

Supported request methods

  • Preferred: send QUERY directly when your HTTP client supports custom methods.
  • OpenAPI-compatible fallback: send PATCH with the same JSON body.
  • Proxy/client fallback: send POST or PATCH with X-HTTP-Method-Override: QUERY.

Dynamic query request bodies

List endpoints that expose filtering, sorting, pagination, and export options accept a query object. The most common fields are:

  • filter: filter conditions or composite filter nodes.
  • sort: ordered sort fields.
  • pagination: zero-based page and page size.
  • exportFormat: Json, Csv, or Xlsx.
  • returnPropertyInfo: include filterable property metadata when supported.

Guidance for integrators

  • Treat QUERY and PATCH-documented query endpoints as read/query endpoints when used with an empty or query-style JSON body. Do not assume they modify server state unless explicitly documented.
  • Continue to use correct HTTP semantics for endpoints that truly update resources, such as PUT, POST, and DELETE.
  • Generated OpenAPI clients will normally call PATCH; this remains supported.