Versioning
The version lives in the path: /api/v2. Don’t set the X-API-Version header: it only accepts v1 and would make the call fail with 400.
v1 vs v2
Section titled “v1 vs v2”| v1 | v2 | |
|---|---|---|
| Path | the app’s internal routes (/api/…) |
/api/v2/…, an isolated, versioned surface |
| Response shape | raw database shapes, not standardized | stable envelope { data, meta } / { error } |
| Status | deprecated for API keys | active, the recommended surface |
| Compatibility | stays reachable for compatibility | additive: resources/fields are added, never removed |
v1 — the routes used by the app — stays reachable to API keys for compatibility, but it’s deprecated: responses carry Deprecation: true and a shutdown date (Sunset: 2027-03-08). Every new version gets at least 12 months of overlap with the previous one: no public route disappears overnight.
v2 contract compatibility
Section titled “v2 contract compatibility”The v2 contract is stable: no breaking change within it.
- Allowed: adding new resources, adding new fields to existing DTOs.
- Not allowed: removing or renaming a public field, changing the meaning of an
error.code— that kind of change requires a v3, not a v2 update.
If you’re integrating today, you can rely on a call that works continuing to work: fields can only be added, never disappear or change shape.