Skip to main content

API deprecation & versioning policy

This policy is rendered from api-policy.yaml — the same file the changelog validator enforces in CI, so the promises on this page and the checks in the release pipeline cannot drift apart.

Versioning​

The public API is versioned in the URL path: the current version is v1 (https://api.staging.tessera.zone/v1, https://ingest.staging.tessera.zone/v1). A breaking change is never shipped inside an existing version — it ships as a new version path (for example, /v2), per our API conventions. When a new version ships, the previous version remains fully supported until every operation it serves has either a non-breaking equivalent in the new version or has passed its announced sunset date — an API version is never turned off while any of its operations is inside its deprecation notice window.

Deprecation notice window​

When an operation, field, or parameter is deprecated, it keeps working for at least 365 days (min_deprecation_notice_days: 365) from the day the deprecation is announced in the changelog. Every changelog entry tagged deprecated carries a sunset_date at least 365 days out; CI rejects any entry that violates the window.

How deprecations are announced​

  • The changelog entry is tagged deprecated and states the sunset_date.
  • The operation is marked as deprecated in the API reference.
  • Responses from deprecated endpoints carry the Deprecation and Sunset headers: the sunset timestamp they advertise matches the changelog's sunset_date.

Error codes​

The error envelope's code set is closed and only grows (error_code_policy: closed set, grow-only, never repurposed): new codes may be added in a version, existing codes are never removed and never repurposed within it. See the API reference for the current set.