Versioning and deprecation

The version is in the path

Every dataset endpoint lives under /v2. A new major version appears as a new prefix rather than as a change in behaviour behind the existing one, so a caller pinned to /v2 keeps receiving /v2 semantics for as long as /v2 answers at all.

What we treat as a breaking change

The test is whether a correct integration could stop being correct without changing. If it could, the change is breaking and does not ship inside a version.

• Removing a field, or changing its type, units or meaning.
• Removing an endpoint, or narrowing what it accepts.
• Changing the grain of a row — what one row represents.
• Making an optional parameter required.
• NOT breaking: adding a field, adding an endpoint, adding an optional parameter, or widening what an existing one accepts. Parse defensively — new fields will appear.

Notice before a surface is withdrawn

A deprecated endpoint keeps answering for at least 90 days after it is announced. During that window it behaves exactly as before — deprecation is a statement about the future, not a change in the response. Datasets in a `building` grade are excluded: they are explicitly not yet stable, which is what that grade means.

Every response carries its rate limit

Three standard headers accompany every response, whether or not it carried a key — including the 401 you get for calling a keyed dataset without one. They follow draft-ietf-httpapi-ratelimit-headers, so an HTTP client's own backoff logic reads them without being taught anything about us.

• `RateLimit-Reset` is a number of SECONDS, not an absolute time. An absolute time would require both clocks to agree, and a client running five minutes slow would retry early — turning a 429 into a steady loop.
• A 429 also carries `Retry-After`. RateLimit-* is still a draft, so sending only the new headers would say nothing to an older client; both go out together.

RateLimit-Limit      quota for this windowRateLimit-Remaining  calls leftRateLimit-Reset      seconds until reset  (delta-seconds, NOT a timestamp)Retry-After          sent additionally on 429

How a withdrawal is announced

The mechanism is in place: `Deprecation` carries the moment an endpoint was declared deprecated and `Sunset` the moment it stops answering (RFC 9745 / RFC 8594), with a `Link rel="deprecation"` pointing here. A machine client should read those rather than watch this page.

No endpoint is currently being retired, so you will not see those headers on a response today. Their absence is the announcement — the mechanism was built BEFORE it was needed on purpose, because adding a header on the day of withdrawal is no warning at all to an integration written before the announcement.

An endpoint with no declared retirement carries no deprecation header at all, rather than an empty one. A `Sunset:` with no value breaks strict parsers and says exactly what sending nothing says.