Versioning and changes

The version is in the address: /v1. Within it, the API only grows.

What may change within /v1

• A new endpoint.
• A new optional parameter or request field.
• A new field in an answer.
• A new error code, or a new value where the reference says more may come, such as a page section’s type.

So your code must ignore fields and codes it doesn’t know. Don’t reject an answer for an extra field, and treat an unknown error code by its HTTP status.

What never changes within /v1

Removing or renaming an endpoint, a field, a parameter or a type; making an optional input required; changing a type, a format or what a value means; or narrowing what a request accepts. A change like that is breaking: it waits for a new version, /v2, announced at least six months ahead.

Where changes are announced

• The changelog lists every change to the public API, newest first, with breaking ones marked.
• The reference and the spec, openapi.yaml, are generated from the API’s own contract, so they describe exactly what it answers. The API serves the same spec at /openapi.json.