Skip to content

Reference

API versioning and deprecations

Tested with:Databasezy API 1.0.0 · RFC 9745 · RFC 8594

The API at https://api.databasezy.com/v1 is versioned by its path. Within /v1 it only grows: new operations, new optional parameters and fields, and new values of enums the API returns. Nothing in /v1 is renamed, retyped or made stricter in place; a breaking change becomes a new operation (or a future /v2), never an edit of an existing one. Write clients that ignore fields they do not know; the SDKs already do.

When an operation has a better replacement, it is marked deprecated in the OpenAPI document (deprecated: true) and announced in the SDK changelog. It keeps working, and every answer to it, errors included, carries three headers:

response headers of a deprecated operation
Deprecation: @1792022400
Sunset: Mon, 01 Nov 2027 00:00:00 GMT
Link: <https://docs.databasezy.com/reference/api-deprecations#instances_list>; rel="deprecation"; type="text/html"
  • Deprecation (RFC 9745) is the date the deprecation took effect, as Unix seconds after @.
  • Sunset (RFC 8594) is the earliest date the operation may stop answering.
  • Link with rel="deprecation" points at the operation’s row on this page, which names its replacement.

The sunset is always at least 12 months after the deprecation is announced. Before the sunset the operation works exactly as before. A /v1 operation is not removed from /v1 even after its sunset; it can only be left out of a later major version of the API.

No operation of API 1.0.0 is deprecated. Every /v1 operation in the OpenAPI document is fully supported.

The Go, TypeScript and Python SDKs carry the API contract version (info.version of the OpenAPI document) and are released together; their changelog lists every deprecation with its sunset date. See SDKs.