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.
How an operation is deprecated
Section titled “How an operation is deprecated”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:
Deprecation: @1792022400Sunset: Mon, 01 Nov 2027 00:00:00 GMTLink: <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.Linkwithrel="deprecation"points at the operation’s row on this page, which names its replacement.
The 12-month window
Section titled “The 12-month window”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.
Deprecated operations
Section titled “Deprecated operations”
No operation of API 1.0.0 is deprecated. Every /v1 operation in the
OpenAPI document is fully supported.
SDK versions
Section titled “SDK versions”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.