Versioning
Versioning policy
Stripe-style additive. We add new versions without removing the old. You migrate at your pace, with at least six months' notice.
Current
v1 — path prefix /api/v1/. Header X-API-Version: v1.
What counts as breaking
Any of these requires a new major version:
- Removing or renaming a field, query param, or path
- Changing a field's type
- Tightening validation (request worked before, now 400s)
- Changing the meaning of a value (enum reused for new state)
- Changing a default that affects behaviour
- Tightening auth or scope semantics
These are not breaking and ship within the current major:
- Adding new fields to responses (clients ignore unknown fields)
- Adding new optional query params or body fields
- Adding new endpoints
- Loosening validation (request that 400d before now 200s)
- Adding new scopes (existing keys keep their scopes)
Lifecycle
| Phase | Duration | Behaviour |
|---|---|---|
| ACTIVE | indefinite | Default version. X-API-Version reflects this. |
| DEPRECATED | ≥ 6 months | Endpoint still works. Adds Sunset + Deprecation + Link headers. |
| SUNSET | final 24h | We email all keys that hit the endpoint in the last 30 days. |
| REMOVED | — | Endpoint returns 410 Gone with a Link to the migration doc. |
The 6-month window is a floor, not a ceiling. Most deprecations run 9–12 months. We only shorten to 6 if security or correctness demands.
Deprecation headers
When you call a deprecated endpoint, your response carries:
Sunset: Thu, 01 Oct 2026 00:00:00 GMT
Deprecation: @1745847600
Link: <https://lazynext.com/docs/api/changelog#v2>; rel="deprecation"Per RFC 8594 (Sunset) and the IETF deprecation header draft (Deprecation). Watch for them in your client and surface them in your monitoring.
Communication
- Deprecation announcement on the API changelog.
- Email to all keys that hit the endpoint in the last 30 days.
- Banner on this docs page.
- Sunset reminder emails at T-90, T-30, T-7, T-1 days.