API versioning and deprecation policy

Rules

1. Within a major, only additive changes:
   • allowed: new routes, new optional query parameters, new response fields, new enum values in responses, looser validation of input, new error codes for new situations, doc text;
   • breaking (needs /v2): removing or renaming a route, field or parameter; making a parameter or field required; a new required parameter; changing a field's type, format or meaning; a response field that may now be null or missing; fewer accepted input values; a changed success status; a route that stops accepting anonymous calls (in the document; what anonymous callers may do at runtime is policy, see "Anonymous tier" below).
   • Clients must ignore unknown response fields and tolerate unknown enum values (stated in the OpenAPI description).
2. Data, not only shape. Changing what a field means (units, currency, a count's definition) is breaking even if the type stays: add a new field instead and deprecate the old one.

Anonymous tier

• Anonymous answers keep the schema (lists may be shorter, nextCursor null, text cut) and add an anonymous field and the x-arcadium-anon: true header.
• Never remove or change a response field for keyed callers under this heading: that stays a breaking change.

In short

• /v1 is stable. Breaking changes go to /v2, side by side.
• A deprecated route keeps answering until its Sunset date, at least 180 days after the deprecation. Responses carry the Deprecation, Sunset and Link headers; key holders also get an email at deprecation and 30 days before the sunset.
• Clients should ignore unknown response fields and tolerate new enum values.