Versioning
What may change in v1 and what never does.
v1 is frozen: no field disappears or changes type; what comes is a new field or resource, documented in the OpenAPI and the release notes.
The v1 rule
- A published field is never removed nor changes type.
- A published resource never changes URL nor list order.
- Changes are additive: new field, new optional parameter, new resource. Your code should ignore fields it does not know.
- A breaking change becomes /v2, with v1 kept up during the transition and a notice in the API history.
Contract version today
v1.2.0 openapi.json declares the version in info.version; the generated SDK carries the same version.