How to handle API updates and versioning
|Structured representations (application/json)|
Content type negotiation
The Accept header may include the v parameter to specify the API version requested; see “Versioning” below.
a new (breaking/major) version of a set of public-facing APIS should be an entirely new domain (e.g. v2.my-api.example.com), with entirely segregated infrastructure.
Even though adding pagination support to an existing API is purely additive from API surface perspective, it is a behavior-breaking change
This page provides more detailed explanations for the list of breaking and non-breaking changes given in the Versioning section.
|Backwards-compatible (non-breaking) changes|
|Backwards-incompatible (breaking) changes|
|Guidelines for existing services and versioning of services|
|Don’t Break Backward Compatibility|
|Use Media Type Versioning|