Versions and compatibility

The version is in the path, and it is v1. There is no header to negotiate, no date to pin, and no minor version: a URL that worked keeps working, or the version number changes.

What that promise is worth is the list below — the changes that are forbidden inside a version, and the ones you should expect at any time. The second list is the one to build against: a new field can appear in any response, and a new value in any enum, so a client that rejects what it does not recognise will break on a release that broke nothing. Ignore unknown fields, and treat an unknown enum value as a value you do not handle rather than as an error.

Watching for a change is reading the reference: the documents this site renders are generated from the running service, in the same build that produces it, so a release moves them both. There is no changelog that can be out of date with respect to the API, because there is no step between them.

18. Versioning and compatibility

• The version is a path segment: v1, v2. No dotted or dated versions, no Accept header negotiation — the CDN in front of this API does not vary on Accept (a fact already paid for once, in the markdown-twin design).
• Within a version, these are breaking and forbidden: removing or renaming a field, path or parameter; narrowing a type; adding a REQUIRED request field; changing a default; changing a status code for an existing condition; changing an id's format.
• These are non-breaking and allowed any time: adding an optional request field, adding a response field, adding an enum value (clients tolerate unknowns, §11), adding an endpoint, adding a details entry.
• Removing anything takes a new version running side by side. A version is removed only when its last consumer is gone — verified by access logs, not by belief.
• A field being retired is marked deprecated in the OpenAPI document with the replacement named, and keeps working for the life of the version.