Skip to content

API Standards

Status: Proposed baseline

API surfaces

  • /api/public/v1/... — managed/custom public experiences.
  • /api/tenant/v1/... — tenant console and tenant operations.
  • /api/platform/v1/... — platform operators only.
  • /webhooks/... — provider callbacks with provider-specific verification.

Custom/headless access is permitted only for tenants under a Custom contract even when endpoints are technically part of the public API surface.

Contract rules

  • OpenAPI 3.1 is the canonical HTTP contract format.
  • UUID/ULID-style opaque identifiers; no sequential IDs exposed as an authorization mechanism.
  • RFC 3339 timestamps in UTC; tenant locale/timezone only for presentation and local business-rule interpretation.
  • Monetary values transmitted as integer minor units plus ISO currency where applicable.
  • Cursor pagination for large collections.
  • Structured error envelope with stable error codes.
  • Idempotency-Key required for payment/booking/order/quote-acceptance operations that can create financial or inventory side effects.
  • Optimistic concurrency/version field for high-conflict administrative resources where needed.
  • Request correlation ID returned and logged.
  • BCP 47 locale identifiers for explicit locale parameters/metadata.
  • Locale resolution/fallback must be deterministic for localized resources; APIs must not infer currency or timezone from locale.

Example error envelope

{
  "error": {
    "code": "AVAILABILITY_CONFLICT",
    "message": "The selected resource is no longer available.",
    "details": {},
    "requestId": "..."
  }
}

Compatibility

Breaking API changes require a new major API version or an explicitly managed migration window. Internal module contracts may evolve faster but must retain test coverage at engine boundaries.

Internationalization contract

Public/headless APIs may negotiate locale through documented route/query/header mechanisms. When fallback materially affects a localized response, the contract must be able to expose requested vs resolved locale and whether fallback occurred.

Canonical timestamps remain RFC 3339/UTC at API boundaries unless a domain-specific local-time contract is explicitly required. Operational schedules retain their authoritative IANA timezone separately. Currency amounts remain minor-unit + ISO currency values independent of locale formatting.