Glossary
Last Updated Apr 12, 2023

API Versioning

Emma Jagger

Table of Contents:

Get your free
API key now
4.8 from 1,863 votes
See why the best developers build on Abstract
START FOR FREE
Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.
No credit card required

What is API Versioning?

"API versioning is the practice of transparently managing changes to your API." Just like any other software, APIs have versions. When a lot of customers depend on an API's endpoints and services, one change could break a lot of software across the web. How do software engineers negotiate versioning?  

API Contracts

Similar to legal contracts, API contracts govern interactions between the downstream service (consumer) and the upstream service (provider) and list all the methods with which a consumer can interact with the provider. A "breaking change" is a change in these contracts, such as:

  • Changing the request/response format (e.g. from XML to JSON)
  • Changing a property or API parameter name (e.g. from name to productName) or data type on a property (e.g. from an integer to a float)
  • Adding a required field on the request (e.g. a new required header or property in a request body)
  • Removing a property on the response or the API payload (e.g. removing description from a product)

These changes "break" the contract and force API users to change their code to interact with the API. Of course, software developers need to improve their APIs, and users need to keep using them. This is where clear communication and versioning can help.  

How should I Version an API?

There are different methods of versioning an API:

  1. URI (Uniform Resource Identifier) versioning. This means changing what the API is called in a request- for example, `http://myapi.example.com` becomes `http://myapiv2.example.com`
  2. Versioning using Custom Request Header. This reads the version of the incoming call with a query parameter and delivers that version of the API.
  3. Versioning using Accept header. This adds a custom header to requests that looks like `Accept: version=1.0`, to specify what version of the API is being requested.  

Conclusion

API versioning is ideally guided by API management core principles. Always following engineering best practices, but also communicate clearly with your customers so versioning goes smoothly for everyone.

Get your free
API
key now
4.8 from 1,863 votes
See why the best developers build on Abstract
Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.
No credit card required