Concepts
Versioning
What's frozen, what's additive, and how breaking changes ship.
The contract
- Paths and response field shapes under
/api/v1/are frozen for the life of v1. - Additive changes (new endpoints, new optional response fields, new error codes, new query params with defaults) ship without notice.
- Breaking changes (rename, remove, type change, semantics change) only
ship under a new major version:
/api/v2/. - Both versions run in parallel; we publish a deprecation date for v1 only after v2 has been stable for at least 12 months.
What "frozen" means in practice
- A field present in a v1 response today will still be present in 18 months.
- It will still have the same type.
- If we want to change the type, we add a new field and leave the old one alongside.
- Error codes don't get renamed. We can add new ones; we don't remove existing ones without a major version.
- Scope strings (
products:readetc.) are part of v1 — they live forever within v1.
What "additive" looks like
Things that have already shipped without a version bump:
Product.isFeaturedboolean — new field; old clients ignore it.OrderSummary.statusenum gainedON_HOLDandDISPUTED— old clients may not have a case for them.- A new query parameter
categorySlugonGET /v1/store/products.
If you switch on enum values, default-case them safely. If you pick from
response objects, you'll only see fields you ask for.
Detecting your version
The OpenAPI document at
/api/v1/openapi.json has a
info.version field ("1.0.0" at time of writing). Patch bumps (1.0.1)
mean additive changes; we will document each in the changelog.
There is currently no per-response version header. If you need one, mail us.
Deprecation policy
- A field, endpoint, or error code becomes deprecated by being marked
deprecated: truein the OpenAPI spec and announced in the changelog. - A deprecated thing keeps working for at least 12 months after the announcement.
- Removal happens in the next major (v2). We never silently remove from v1.
Pre-release endpoints
Some endpoints land as x-stability: experimental in the OpenAPI spec. They:
- Are functional and tested.
- Can change shape without a major version.
- Are documented but flagged with a warning in this site.
Don't bake experimental endpoints into customer-facing flows.