The API will inevitably need to be modified in ways that will impact customer client code. Not all customer clients will be able to make the necessary changes in their code right away, so the API should maintain older versions for some time after releasing the new version, usually a minimum of 90 days.
When to Version
APIs only need to be upversioned when a breaking change is made. Breaking changes include:
- a change in the format of the response data for one or more calls
- a change in the response type (i.e. changing an integer to a float)
- removing any part of the API.
Some example breaking changes would be:
- Changing the expected type of a number from an Integer to a Float/Decimal value.
- Eliminating the “country” value from an address response because you’re no longer an international company.
- Adding a new “status” type to an expected enumeration response.
Breaking changes should always result in a change to the major version number for an API or content response type.
Non-breaking changes, such as adding new endpoints or new response parameters, do not require a change to the major version number. However, it can be helpful to track the minor versions of APIs when changes are made to support customers who may be receiving cached versions of data or may be experiencing other API issues.
Versioning Content Types
The use of content negotiation with custom MIME types allows for finer grained versioning at the resource level without the need to create a plethora of new endpoints. New versions must be communicated to developers through existing channels – email, developer blogs, etc. When a content version is no longer supported, the body of the HTTP error should include a list of supported content types.
The use of both hyper links and content negotiation should all but eliminate the need to version at the URI level. However, there may be instances where the entire structure of the API must be changed, particularly when moving from one API style to another, such when moving from an RPC-type style to NARWHL. To prepare for these possibilities, it’s recommended that a version be embedded within each API endpoint. The version can either be embedded at the root for all endpoints of a given API, such as:
Or within the fully qualified domain name for the endpoint:
The version need not be numeric, nor specified using the “v[x]” syntax. Alternatives include dates, project names, seasons or other identifiers that are meaningful enough to the team producing the APIs and flexible enough to change as the versions change.