Versioning and deprecation
The version is in the address. Inside a version changes only add, and an old version keeps working for 12 months after the next one is out.
Last updated 3 min read
On this page · 3 sections
The version is in the address: /v1. This is version 1.
- Inside a version, changes only add: a new field, a new endpoint, a new optional argument. Write your tool to ignore a field it does not know.
- A change that could break your code ships as a new version, such as /v2.
- The old version keeps answering for 12 months after the new one is generally available.
- For the last 6 of those months every answer carries a Deprecation header, a Sunset header with the last day, and a Link to this policy.
- After the last day the old version answers 404 not_found for every address.
What counts as adding, and what breaks
| Inside a version (adding) | A new version (could break you) |
|---|---|
| A new field in an answer | A field removed or renamed |
| A new endpoint | A field's type changed |
| A new optional argument | An argument made required |
| A new error reason | A status code moved |
The headers near the end
An example, for a version whose successor shipped on June 1, 2027:
Deprecation: @1811808000 Sunset: Thu, 01 Jun 2028 00:00:00 GMT Link: <https://current.day/developers/versioning>; rel="deprecation"; type="text/html"
How long does Current support an old API version?
12 months after the next version is generally available. For the last 6 of those months every answer carries Deprecation and Sunset headers with the last day. Inside a version, changes only add. See the current-api-versioning article. The Current API is not open yet.
Was this helpful?