Skip to content

APIs

Use this section for REST and HTTP integration flows, authentication behavior, error semantics, pagination, and lifecycle guidance.

Interface contract

The OpenAPI specification is the authoritative machine-readable endpoint and schema reference. Keep it versioned with the service change that alters the contract. Do not duplicate endpoint or payload definitions in Markdown.

Adding a service

  1. Add the service's versioned OpenAPI file under docs/api/spec/ (or its own service subdirectory when it grows).
  2. Link that file from the service's integration guide.
  3. Explain only cross-endpoint workflows, semantic invariants, and operational constraints in prose.
  4. Validate the specification in the service CI and review its diff with the implementation.