API versioning best practices

Release breaking changes without disrupting existing clients.

Problem statement

It's typical for an API product to evolve over time as new features are added, existing features are modified, bugs are fixed, and occasionally existing features are retired.

In most cases it is best practice to make changes to an API in a backwards-compatible way, to not disrupt existing customer integrations. Sometimes making a breaking change is unavoidable. In these circumstances, it is desirable to release the change to a controlled subset of customers, without impacting the rest.

Success criteria

Versioning helps improve trust and confidence in an API by avoiding breaking client integrations.

Of course, the purpose of each new version is to deliver greater value to customers. Metrics should measure adoption to assess whether the benefit provided by a new version outweighs the migration cost for consumers.

Product requirements

API versioning provides a mechanism to deliver previous and new functionality and behavior to different customers simultaneously.

Strictly speaking, the API's version only needs to change when a breaking change is introduced. For non-breaking changes, the API can be updated without increasing the version. This approach keeps the API version relatively stable.

The downside of only increasing the API's version for breaking changes is that it makes communicating other enhancements less clear as they are no longer tied to new version numbers. This can be mitigated by using semantic versioning, where only the major version number needs to be specified, but the changelog can describe the full version number.

User stories

As a developer, I want the API's contract to remain stable for a given version, so that I can integrate against a consistent interface.Functional

An API contract is a promise, which developers expect to be upheld. There are a number of valid strategies for upholding this promise:

1. Never change the API contract for a given version. Always increment the API version for each change to the contract.
2. Only release backwards-compatible changes to a given API version. Only increment the API version for breaking changes.
3. If using Semantic Versioning, advise developers that changes to minor and patch versions will always be backwards compatible, and that they can pin their integration to the major version only.

As a developer, I want to pin my application to a particular a version of the API, so that my integration doesn't unexpectedly change behaviour or break when a newer version of the API is released.Functional

Major version updates should always be opt-in. Allow the client to specify the API version that their integration uses, either through internal configuration or through the API request itself.

If the client's version is determined from an internal configuration, your customer will have to coordinate with you to perform migrations. This can be costly and time consuming for both the API consumer and provider. Prefer to provide a self-serve mechanism for specifying the API version.

As a developer, I want to specify which version of the API to use on a per-request basis, so that I can migrate my integration to a newer version incrementally.Functional

Allowing the client to specify which version of the API to use on a per-request basis gives the client the most amount of flexiblity and control:

1. The client can opt-in to new versions at will.
2. The client can specify different versions in different environments. For example, the client can specify version 1 in their Production environment, and version 2 in their QA environment.
3. The client can migrate a portion of their integration to a new version, while keeping the rest of the integration the same.

This approach can be combined with a default version configuration, such that the per-request version acts as an optional override.

As a developer, I want to receive a clear and helpful error when the requested API is no longer supported, so that I can remediate the problem as quickly as possible.Exception

When returning errors due to version mismatch, it is a good idea to include links to the any relevant versioning policies, changelogs, and migration guides in the human-readable portion of the error response.

As a product team, I want to prevent new customers from accessing deprecated APIs, so that the risk of clients not being able migrate before the sunset date does not increase.Exception

Once an API is deprecated, existing clients should be able to continue access it, but new clients should not.

You can store the minimum supported version per API client, so that client credentials issued after a certain date cannot be used to access APIs that were deprecated on that date.

As a DevSecOps team, I want release security fixes immediately without disrupting existing integrations, so that vulnerabilities can be remediated as quickly as possible.Security

Any mechanism that allows the client to specify which version of an API to use needs to consider whether clients should opt in or opt out of receiving security updates.

If your API uses Semantic Versioning, an opt-out approach could be to allow clients to specify only the major and minor version to use, without a patch version, i.e. major.minor. This ensures that when you release a security update as a patch, all customers will receive it automatically. Customers can opt out of this behavior by specifying the full semantic version, i.e. major.minor.patch.

As a developer, I want the API documentation to clearly indicate the current API version and any version-specific behavior, so that I can accurately integrate and test against the correct version.Documentation

If your reference documentation is backed by OpenAPI, Operation and Paramter objects support a deprecated field to declare them as deprecated.

As a developer, I want the changelog to clearly distinguish backwards compatible enhancements from breaking changes or removals, so that I can peform cost-benefit analysis when deciding to upgrade.DocumentationOperations

If a release that doesn't include any breaking changes, the developer may decide to migrate to it immediately since it is a lower risk.

As a developer, I want to receive adequate notice an API will be deprecated and sunsetted, so that I can prioritize my backlog effectively and avoid service disruptions.Operations

All APIs should have a deprecation policy, which stipulates that deprecated APIs will continue to be supported for a period of time, such as 12 months.

During the deprecation period, notify customers who haven't migrated on a periodic basis with increasing frequency.

Customers may need to incorporate the effort in their overall backlog, staff on-call resources and notify customers. Sometimes a customer cannot prioritize the appropriate resources before the sunset date. Depending on the relationship you have with your customers, you may need to be prepared to extend the migration deadline for the last few customers.

Explore design patterns

API examples

Further reading

• https://restfulapi.net/versioning/
• https://www.infoq.com/articles/roy-fielding-on-versioning/
• https://zuplo.com/blog/2022/05/17/how-to-version-an-api
• https://labs.qandidate.com/blog/2014/10/16/using-the-accept-header-to-version-your-api/
• https://cloud.google.com/blog/products/api-management/api-design-which-version-of-versioning-is-right-for-you

Related topics