Versions and end dates¶
Every call goes to /api/v1. That prefix is the version: as long as it answers, what you built
keeps working.
What changes inside a version¶
Inside v1, things are only added: a new optional request field, a new response field, a new
route, a new value in a list that already had several. Write your client so that an unknown field
in a response is not an error and you will never notice any of it.
A field that disappears, a type that narrows, an optional field that becomes required, a different
status code, a renamed route: none of that ever happens inside v1. A change like that gets its
own version, /api/v2.
How long a version keeps answering¶
Once /api/v2 arrives, /api/v1 keeps answering for another twelve months. The end date is
fixed on the day v2 ships and does not move afterwards. So you have a full budget year to move
across, and you do not have to ask for the date: you read it from the responses you are already
getting.
The two headers¶
As soon as an end date exists, every response under /api/v1 carries two headers — errors
included, precisely because a caller who only reads its own logs would otherwise miss it:
Deprecation: @1790812800
Sunset: Fri, 01 Oct 2027 00:00:00 GMT
Deprecation is the day the end was announced, as seconds since 1 January 1970
(RFC 9745). Sunset is the day the version stops
answering, as an ordinary HTTP date
(RFC 8594).
If you do not see these headers, nothing has been announced and v1 is simply current. If you do
see them, check that your client logs or surfaces them; that is the cheapest way not to miss a date
like this.
Tell whether the contract changed¶
The contract your deployment publishes at /api/openapi.json
carries two values in its info object:
| Field | What it tells you |
|---|---|
info.version |
the release of Core your deployment runs, the same number its release notes carry. A deployment that runs a build ahead of the next release, such as a test environment, names the release that build will become. It reads 0.1.0 until the first release, and additions made before then do not change it. A new release never changes the /api/v1 path |
info.x-contract-digest |
a SHA-256 fingerprint, in hex, of the routes and schemas in that document. It changes with every change to the contract, also between releases, and stays the same when nothing in the contract changed |
If you generate a client from the contract, store the digest of the document you generated it from. When the live digest differs, the contract has changed: generate again and look at what was added.
The status checks belong to no version¶
/api/health and /api/ready sit outside /api/v1. They never carry these headers, and their
addresses do not change when a new version arrives.