← Zerocost developers

Zerocost API versioning and deprecation policy

How the Zerocost API is versioned, what can change within a version, and how deprecations and removals are announced.

Versioning

  • The API version is in the URL path (/api/v1) and in the API-Version response header.
  • Within v1, changes are additive only: new endpoints, new optional parameters and new response fields. Clients should ignore fields they do not recognise.
  • Breaking changes ship as a new version (/api/v2). The previous version keeps working alongside it.

Deprecation and sunset

  • Before a v1 endpoint or field is removed, its responses carry a Deprecation header (RFC 9745) and a Sunset header (RFC 8594) at least 90 days before the removal date.
  • Deprecated responses also carry a Link header with rel="deprecation" pointing at migration notes.
  • Deprecations are announced on this page, in /auth.md and in the OpenAPI spec (operations are marked deprecated: true).

Current status

  • v1 is the current version. No endpoints are deprecated.

Machine-readable: OpenAPI spec · this page as markdown