Versioning and deprecation

Your integration ships to stores that update it when they get round to it, so it has to keep working while the API moves on. This guide is about what the API promises between releases, and what you have to handle to hold it to that.

Releases

The reference is released as a version, info.version in the document. Each release is published with the reference it describes and a changelog of what changed since the previous one. Pin a release, not whatever the API serves today, and read the changelog before you move to the next.

A release is published in two places. The tag api-v<version> has a GitHub release carrying openapi.json, webhook-signature-vectors.json and CHANGELOG.md; that repository is private. Pixonaut’s CDN serves the same three files without a token, at

• https://cdn.pixonaut.app/api/<version>/openapi.json
• https://cdn.pixonaut.app/api/<version>/webhook-signature-vectors.json
• https://cdn.pixonaut.app/api/<version>/CHANGELOG.md

and integrity.json beside them lists each file’s checksum. A published version never changes, so an integration’s CI pins a version and the checksum of the file it fetched, and fails if either stops matching.

Versions follow what the reference did:

• a new major version may break a client written against the previous one;
• a new minor version only adds: an operation, an optional field, a value;
• a new patch version changes nothing you can rely on.

A breaking change made within a major version is listed in the changelog with the reason it was agreed with the integrations it affects.

Values that grow

A status, a refusal’s error code and every other value the API sends from a fixed set of possibilities is listed in the reference as an open set (x-extensible-enum): the values known at this release. A later minor release can add one. Handle a value you do not know instead of failing on it: treat an unknown order status as still in progress, and an unknown refusal code by its HTTP status, which keeps its meaning. A refusal names its code in error. The fields beside it are optional in the reference, since a code added later may not send them, and each one’s description says which codes always do.

Deprecated fields

A request field the API stops reading is deprecated before it is removed. It is still accepted for 6 months from the day it is deprecated. While a field is deprecated, a request that still sends it is answered as if it had not, and the response carries two headers:

• Deprecation: when the field was deprecated, as @ and Unix seconds;
• Sunset: the date it stops being accepted, as an HTTP date.

Log both when you see them: they are the notice to stop sending the field. From the sunset on, a request sending it is refused 400 with field_removed, naming the field in field. The reference marks a deprecated field deprecated, with both dates.

A field whose absence would change what is made, counted or charged is not ignored: dropping it quietly would turn your request into a different one. Such a field is refused by name from the day it stops being read, with a code that says where it went. How many copies to print moved to the order that way, so POST /v1/prints refuses a quantity with quantity_moved_to_order.

Deprecated response and webhook fields

A field the API stops sending, in a response or in a webhook’s payload, is deprecated before it goes, for the same window. Until its sunset it is still sent; a field that was renamed is sent under its old name too, with the new one’s value. A response carrying one has the Deprecation and Sunset headers; a webhook delivery does not, so read the reference’s mark and the release’s changelog. From the sunset on the field is no longer sent. Move to what the field’s description says to read instead before then.

Deprecated operations

An operation due to go is deprecated before it is removed, for the same window. Until its sunset it answers as before, and every response carries the Deprecation and Sunset headers. From the sunset on it is refused 410 with operation_removed, naming it in operation. The reference marks the operation deprecated, with its sunset in x-sunset and both dates in its description.