Versioning

Version in the path

The version is part of the path: /v1. Within /v1 we only make changes that do not break a careful caller: new routes, new optional request fields, new response fields, and new values where a field is documented as open.

A change that would break callers (removing or renaming a field, changing its meaning, tightening validation) goes into a new version, /v2, and /v1 keeps working alongside it for a notice period that we will publish with it.

Ignore response fields you do not know, and send only the fields the OpenAPI document lists.