Public Data API
Versioning contract
The version lives in the path; which changes are ordinary and which are breaking, and the view schema each response names.
Versioning#
| Subject | Rule |
|---|---|
| The version | In the path — /api/v1. There is no version header, no query parameter and no content negotiation. |
| Adding a field | Ordinary, and not announced. Parse defensively: treat an unknown key as data you do not use yet, never as an error. |
Adding an error code | Ordinary. Branch on the codes you handle and fall through on the rest rather than matching exhaustively. |
Changing or removing an error code | Breaking, because a consumer is already branching on it. |
| Renaming or removing a field | Breaking. |
| The underlying view schema | Reported per response as freshness.viewsSchema. It names the database schema the figures were read from, so a response can be traced to the shape that produced it. |