Versioning and stability
The version lives in the URL. What we may change without warning, and what we may not, is written down here.
Version in the path
The current version is v1, served at /api/v1/*. Every response also carries x-api-version and meta.api_version. A future incompatible version would be served at a new path, not swapped in underneath you.
Additive changes can ship any time
- New operations.
- New optional request fields with a backward-compatible default.
- New fields in a response object.
- New error codes for conditions that previously returned a generic error.
- Reworded error messages.
Write clients that ignore unknown response fields and branch on error.code rather than message text.
Breaking changes will not ship inside v1
- Removing or renaming an operation, a request field or a response field.
- Changing the type or meaning of an existing field.
- Making an optional field required.
- Changing the HTTP status attached to an existing error code.
Holiday data updates
Public holiday data changes when governments change it. Corrections are treated as data updates, not API changes, so a past calculation can legitimately produce a different answer after a country revises its calendar. Results record the provider and version so any figure can be reproduced and explained.
The specification is generated
/openapi.json is generated from the same catalog the gateway validates against, and a test fails the build if the two drift apart. The document cannot describe an endpoint that does not exist.