API versioning
Objective
Section titled “Objective”Read this page to know what we may change without warning and what we may not.
Requirements
Section titled “Requirements”- None
Instructions
Section titled “Instructions”How a version is identified
Section titled “How a version is identified”It depends on the protocol, and there is no single answer:
Query-protocol services carry the version as a request parameter:
Version=2016-11-15The SDKs supply it from their own service model; a caller does not set it by hand.
JSON-protocol services carry no version on the wire. The version is part of the action target:
X-Shelf-Target: ShelfBilling_20260101.GetQuoteRequiring a Version parameter from a JSON-protocol client would break every
SDK, because none sends one.
Which versions are accepted
Section titled “Which versions are accepted”For query-protocol services, a version at or before the implemented one is
accepted. A later version is rejected with InvalidParameterValue.
Accepting earlier versions matters: different SDK releases pin different version dates, and hard-rejecting anything but the newest would mean an older but currently supported SDK release fails entirely — contradicting the promise that existing clients work unmodified.
For JSON-protocol services, an unknown target is rejected with InvalidAction.
What is a breaking change
Section titled “What is a breaking change”Never done within a version:
- Removing an action, a parameter or a response field
- Making an optional parameter required
- Narrowing an accepted value range
- Changing the meaning of an error code
- Changing the type or the unit of a field
- Changing the format of an identifier
- Changing the HTTP status returned for an existing error code
Permitted within a version:
- Adding an action
- Adding an optional parameter
- Adding a response field
- Adding a new error code for a genuinely new failure
- Widening an accepted range
Clients must ignore response fields they do not recognise. Stated here explicitly because a client that rejects unknown fields turns every future addition into a breaking change.
Deprecation
Section titled “Deprecation”OPEN (Michael): the deprecation period and the notice given.
Whatever is chosen applies to every service, is stated once, and is honoured: an announced date is not brought forward.
Document history
Section titled “Document history”Every document carries a history. Every change to the contract appears there, dated, with what changed.
A change that is not written down did not happen. The history is what a customer reads when working code stops working, and it is the difference between a provider that changed something and a provider that broke something.