--- title: API versioning and deprecation policy description: How the Cargo Marshal public API is versioned, how a route is deprecated, which headers announce it, and the 6 month minimum notice before removal. --- This page is the versioning and deprecation policy for the [persistence API](/overview/persistence-api) at `/api/v1`. It applies to the REST API and to the OpenAPI document at `/api/v1/spec.json`. ## Versioning `/api/v1` is stable. Within `v1`, changes are additive only: new routes, new optional request fields, new response fields, and new error `code` or `data.reason` values on an existing status. Build clients that ignore unknown response fields. A breaking change is released under a new version, `/api/v2`, and `v1` keeps working alongside it. These count as breaking: - Removing or renaming a route or a field. - Making an optional input required. - Changing a type or a success status. Every change to the spec is checked for breaking changes before it ships. ## Deprecation Before a route or field is removed, it is marked `deprecated: true` in the OpenAPI document. Every response from a deprecated route, successful or not, carries: - `Deprecation`: `true`, or the date the route was deprecated in the [RFC 9745](https://www.rfc-editor.org/rfc/rfc9745) form `@`, for example `Deprecation: @1790812800`. - `Sunset`: the removal date as an HTTP date ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)), for example `Sunset: Thu, 01 Apr 2027 00:00:00 GMT`, once it is set. - `Link: <…>; rel="deprecation"`: the page that explains the migration, once it is published. ## Minimum notice The sunset date is at least 6 months after the deprecation is announced. The route keeps working unchanged until that date. ## What to do in your client - Log `Deprecation`, `Sunset`, and `Link` headers so a deprecation does not go unnoticed. - Alert on a `Sunset` date that is closer than your release cycle. - Follow the `deprecation` link for the migration steps. No `v1` route is deprecated today.