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.

Versioning URIs

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.

2 thoughts on “Versioning”

  1. In the ‘When to Version’ section should you mention APIs that use enum types? My company’s API reference documentation has attributes with an enum type and we list all values. We ran into a problem when a requirement added an enum value to an existing attribute and it broke a partner app. The partner had coded to the defined enum values in the documentation and their app wasn’t expecting new values with future releases. I corrected the problem by removing the new enum value and I defined any request to add a new enum value to an existing attribute requires a new API version. Last, going forward new attributes with an enum type will be defined as String in the documentation and we will indicate the values are not limited to the ones defined.

    1. This is an excellent point. Basically, a breaking change is any in which you can assume the client had to hard code their ability to address it. In your case, it sounds like the client had to assume that one of N different enum values would be returned, but you added a value that effectively made it an N+1 problem. To me, that’s almost the same as changing the expected type of a response (i.e. sending back a FLOAT when an INT was expected).

Leave a Reply

Your email address will not be published. Required fields are marked *