Versioning and compatibility
The version is the first path segment: every route is under /v1/. This page says what that promises, what can change without a new version, and where changes are announced.
What /v1 means#
- Routes keep their meaning. An endpoint that exists under
/v1/keeps its path, its parameter names, and the meaning of every field in its answer. - Responses only grow. New fields, new endpoints, new platforms, new optional parameters and new error types are added to
/v1without a new version. Fields are not renamed or removed to make room. - Parse defensively. Ignore fields you do not know. Do not fail on an error
typeyou have not seen; branch on the HTTP status first and use the type for detail. See Errors.
Changes that can happen inside /v1#
| Change | Why it is safe |
|---|---|
A new field in data, metadata or pagination | You can ignore it. |
| A new endpoint or platform | Nothing you call changes. |
| A new optional parameter with a default that keeps today's behaviour | Calls that do not send it behave as before. |
A new error type | Reached only by a request that could not succeed before. |
| A value correction (a count that was wrong, a date in the wrong zone) | The field keeps its name and type; only the value was wrong. |
| A format correction (a link that was relative becomes absolute, a number that arrived as text arrives as a number) | The documented type in the unified schema is the one that now holds. |
An endpoint moves from beta to stable | See Data availability. Beta endpoints can change shape when they are verified; that is what beta means. |
| Prices | A price change is shown on the endpoint page and in GET /v1/platforms. The price in force at the time of a call is the one in metadata.credits_charged. |
What is not done to a published version#
- A field is not removed or renamed.
- A type does not change (a number does not become a string).
- A parameter's meaning does not change, and a required parameter is not added to an existing endpoint.
- A fixed-schema field does not change what it means. Platform-specific data lives under
ext.<name>precisely so that it can differ per platform without touching the shared fields. See the unified schema.
Breaking changes#
Anything that would break a correct client under the rules above is a breaking change and does not ship inside /v1. If one is ever needed it ships as a new version path next to /v1, and the change is written up in the changelog before the old behaviour is withdrawn.
How to be safe from it#
- Read only the fields you need, by name, and treat unknown ones as noise.
- For code that must work across platforms, read only fixed-schema fields.
ext.*names are stable for the endpoint that returns them, not across endpoints. - Treat
nullas unknown. See Data availability. - Keep an eye on the changelog, which lists every user-visible change with its date. The OpenAPI document and
GET /v1/platformsalways describe the version you are calling.
Next#
- Unified schema for what the fixed fields mean.
- Response format for the envelope.
- Production checklist.