Skip to main content

​
Contract first

The API contract implemented by each service is the source of truth for its reference documentation. Document the API using the OpenAPI or Swagger version that the service implements. Do not describe an API as OpenAPI 3.1 unless that service has adopted it.

​
Service-specific behavior

Do not assume shared defaults across Lerian APIs. For every operation, document the behavior implemented by that service, including:
  • Authentication requirements and headers.
  • Parameter and JSON field names.
  • Response status codes and date formats.
  • PATCH media type and omitted or null semantics.
  • DELETE behavior and metadata support.
Use the operation schema and handler contract to establish these details.

​
Errors

Error envelopes and error-code formats vary by product. Use the response schema and error reference for the specific service before handling an error programmatically. Do not publish a global error body, prefix, numeric range, or field set unless it is implemented across the services in scope.

​
Reference pages

Render API operation pages from the matching specification rather than duplicating request, response, or error prose by hand. See the API reference template for the operation-stub format.

​
Before publishing

  • Verify the method, path, schemas, and media types against the service contract.
  • Preserve the same method and path in every rendered locale.
  • Update the canonical service contract before synchronizing rendered API specifications.