API versioning and deprecation policy

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 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 form @<unix seconds>, for example Deprecation: @1790812800.
Sunset: the removal date as an HTTP date (RFC 8594), 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.