Versioning

TL;DR: /v1 only 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

  1. /v1 changes only by addition. A change to /v1 is 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 /v1 keeps working beside it. This rule binds /v1 from the day the first live partner key is issued; any change before then is listed in the changelog.
  2. 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.
  3. A deprecated operation says so on every answer. It sends a Deprecation header, the time it was deprecated (@ and a Unix time, RFC 9745), a Sunset header, the date it stops working (an HTTP date, RFC 8594), and a Link header with rel="deprecation" pointing at this page. It is also deprecated: true in the OpenAPI document at GET /v1/openapi.json.
  4. 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 code you have not seen as the general case for its HTTP status. Each of these can appear on /v1 without notice.
  • Watch for Deprecation. Log or alert on any answer that carries the header, so you move off the operation well before its Sunset date.