Reference
Versioning and compatibility
What changes the API makes without notice, and what it promises not to change.
The promise#
The data API is /v1. Within /v1, changes are additive:
- New routes, new optional query parameters and new fields in responses can appear at any time.
- Existing routes, parameters and fields are not removed or renamed, and their meaning does not change. A series whose meaning would change gets a new id.
- New
error.codevalues can be added; clients must tolerate codes they do not know. - New values can appear in documented enums such as
meta.status; handle unknown values gracefully.
Write clients that ignore unknown fields and tolerate unknown codes. The meta object in particular grows keys per family.
What can change without notice#
| Change | Example |
|---|---|
| A dataset starts or stops holding data | A source is switched on after its terms are read; a source is paused. Read meta.status. |
| Rows change content | A publisher revises a number, a statute is amended, a record is delisted. Revisions are kept as versions or marked removed; see Freshness. |
| Limits are adjusted | Rate limits, default key quotas and freshness windows are deployment settings. |
| Attribution text changes | credit is the publisher's current wording. |
Contract files#
The OpenAPI files and JSON Schemas on this site are generated from the same contract the service is tested against. The data API file is checked against the service's router in the service's own tests, so a route cannot exist without being in the spec. If you find the docs and the API disagreeing, the API's behaviour is what you observed; please report it with the x-request-id.
This documentation#
Pages are rebuilt from the contract when it changes. Anything on a generated page ("Generated from ...") follows the contract exactly; authored guides are written to match it. The Markdown and llms.txt outputs are rebuilt with them.
Source: content/reference/versioning.md