Versioning
TL;DR:
/v1only grows. Nothing you rely on is removed or changed in place, a deprecated operation keeps working for at least six months and says so in its headers, and every change to the contract is in the changelog.
The four rules
/v1changes only by addition. A change to/v1is one of these: a new operation, a new optional input field, a new output field, a new error code or a new value of an enum. Anything else (removing or renaming a field, making an optional input required, changing a type or a status) needs a new major path,/v2, and/v1keeps working beside it. This rule binds/v1from the day the first live partner key is issued; any change before then is listed in the changelog.- A deprecated operation keeps working for at least six months. It is marked on the day it is deprecated, and its sunset date is at least six months later. Until then it answers exactly as before.
- A deprecated operation says so on every answer. It sends a
Deprecationheader, the time it was deprecated (@and a Unix time, RFC 9745), aSunsetheader, the date it stops working (an HTTP date, RFC 8594), and aLinkheader withrel="deprecation"pointing at this page. It is alsodeprecated: truein the OpenAPI document atGET /v1/openapi.json. - Every change has a changelog entry. Each version of the OpenAPI document has an entry in the changelog, written the day it is published, which records the document's SHA-256.
What this asks of your code
- Accept what you do not know. Ignore an output field you do not read, and treat an enum value or an error
codeyou have not seen as the general case for its HTTP status. Each of these can appear on/v1without notice. - Watch for
Deprecation. Log or alert on any answer that carries the header, so you move off the operation well before itsSunsetdate.