How to version REST APIs?
In software development, only one thing is inevitable -- change.
As new features are added and the code evolves, the APIs also change.
How do we make sure things don't break?
With API versioning, we can stick to using a specific version of an API, even as new versions are released. This way, we keep using a stable set of APIs, without having to constantly update the code.
Meanwhile, new versions of the API will have all the latest changes and improvements, making it easier for new software to take advantage of all the new functionality.
API versioning is one of the REST API best practices that strikes a balance between change and stability, allowing software to keep moving forward without breaking existing code.
In this article, we'll explore everything you need to know about REST API versioning.
- How to version REST APIs?
- 1. Versioning using URI Path
- 2. Versioning using Query Parameters
- 3. Versioning using Custom Request Headers
- 4. Versioning via Media type
- 5. Versioning using multiple strategies
- FAQ: REST API Versioning
- What is SemVer?
- When to introduce a new API version?
- When not to introduce a new API version?
- What is API contract?
- Which API versioning strategy should I use?
- Why is versioning REST APIs important?
- REST API Versioning Examples
- GitHub Example
- Summary: REST API Versioning
How to version REST APIs?
There are 5 main ways to version REST APIs:
1. Versioning using URI Path
URI Path versioning strategy puts the version number in the path of the URI.
The version number is often prefixed with "v".
Is URI Path versioning REST friendly?
Technically, API versions should not be kept in resource URIs as it goes against the "guidelines of REST".
Resources in REST design don't have a concept of "versions". e.i. What does it mean to request version 3 of the "order" resource?
Instead, to be "fully REST", an API should use HATEOAS.
HATEOAS (Hypermedia as the Engine of Application State) states that the server should provide instructions to the client on how to construct appropriate URIs through media types and link relations.
2. Versioning using Query Parameters
Adding the version query parameter is another easy way to version REST APIs.
Pros:
- Easy to construct the URL.
Cons:
- The URL looks messy when there are other query params
- It's hard to tell whether version number refers to the version of the endpoint or the API itself.
3. Versioning using Custom Request Headers
Custom Request Header versioning strategy lets API consumers pass the version number as a custom header defined by the API designer.
Pros:
- Doesn't clutter the URI path
Cons:
- It's not immediately clear which API client is using
4. Versioning via Media type
Media type versioning (also known as content negotiation or accept header versioning) allows us to version a single resource representation instead of versioning the entire API.
Pros:
- More granular control over versioning
- Creates a smaller footprint in the code base as we don't have to fork the entire application when creating different versions.
Cons:
- Content negotiation is not as user-friendly as URI-versioned APIs because developers have to understand the structure of the header.
5. Versioning using multiple strategies
URI Path, query parameters, or headers?
Why not all?
You can combine many versioning strategies to make life easier for your API consumers.
Pros:
- Better developer UX for consumers
Cons:
- Might be difficult to maintain the codebase
FAQ: REST API Versioning
What is SemVer?
Semantic Versioning (SemVer), created by Tom Preston-Werner, is a specification for assigning version numbers to software.
It solves the problem of meaningless version numbers by providing a clear definition and communication of software intentions. This leads to better dependency management, where software can easily be upgraded without having to roll new versions of dependent packages.
To use Semantic Versioning, follow the version number format, MAJOR.MINOR.PATCH, where:
- MAJOR is incremented for incompatible API changes,
- MINOR for added functionality in a backwards compatible manner, and
- PATCH for backwards compatible bug fixes. Additional labels can also be added for pre-release and build metadata.
For example: 1.2.12
When to introduce a new API version?
A new version of an API should be introduced when you have breaking changes.
What are breaking changes?
Breaking change is any change that breaks the client.
Most common breaking changes include:
- Changing the request/response format (e.g. from XML to JSON)
- Changing a property name (e.g. from name to productName)
- Changing 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)
If you are following Semantic Versioning strategy, breaking changes to the API would require a new major version.
When not to introduce a new API version?
You should not introduce a new version when you have non-breaking changes.
For example when you are:
- Making minor changes that do not affect the existing functionality and do not break the existing code.
- Adding a new endpoints or features that do not alter the existing behavior of the API.
- Making internal improvements to the API, such as performance optimization, without affecting the external behavior.
- Making cosmetic changes to the API, such as updates to documentation or error messages, that do not impact the functional behavior of the API.
What is API contract?
An API contract is a definition of the functionality that an API provides, including the inputs it accepts, the outputs it returns, and the behavior.
The API contract is more of a promise than a contract. You tell the API consumers how the API is going to work and they don't have much to do other than trust you.
Which API versioning strategy should I use?
The choice of API versioning strategy largely depends on the size and complexity of the API, as well as the frequency of changes being made.
- For small and simple APIs, with limited dependencies and a low rate of change, a simple URI versioning strategy may be sufficient.
- For larger and more complex APIs, with many dependencies and a high rate of change, a media type versioning strategy may be more appropriate.
Why is versioning REST APIs important?
API versioning is an important aspect of REST API design as it can affect the long-term commitment to API consumers.
As API designers, we need to understand this
REST API Versioning Examples
GitHub Example
The GitHub REST API is versioned, and new versions are released with a date-based name, such as 2022-11-28.
When a new GitHub API version gets released, the previous version will still be supported for at least 24 months.
To specify which version of the API you want to use, you'll include the X-GitHub-Api-Version header in your API request. If you don't specify a version, the newest version will be used by default.
Breaking changes, such as removing an operation or changing a parameter type, are released in a new version, while additive changes, such as adding a new operation, are available in all supported versions.
GitHub provides a changelog that identifies all the changes.
Summary: REST API Versioning
API Versioning is important because it allows for backward compatibility, enables the introduction of new features without breaking existing clients, and allows for phased rollouts of changes.
Here are the most popular ways to version a REST API:
| Versioning Method | Description | Format |
|---|---|---|
| URI path | The version number is included in the URL path, such as "api/v1/resources" | api/v1/resources |
| Query parameter | The version number is included as a parameter in the URL, such as "api?version=1" | api?version=1 |
| Custom request header | A custom header, such as "X-API-Version" is used to specify the version number | X-API-Version: 1 |
| Content negotiation | The client specifies the desired version through the use of the "Accept" header in the request | Accept: application/vnd.company.resource-v1+json |
The URI path versioning method is the most popular because it is easy to see which version of the API you're using by just looking at the URL.
Keep in mind that different clients can use different versions of your API, so it increases maintenance.
Josip Miskovic is a software developer at Americaneagle.com. Josip has 10+ years in experience in developing web applications, mobile apps, and games.
Read more posts →- How to version REST APIs?
- 1. Versioning using URI Path
- 2. Versioning using Query Parameters
- 3. Versioning using Custom Request Headers
- 4. Versioning via Media type
- 5. Versioning using multiple strategies
- FAQ: REST API Versioning
- What is SemVer?
- When to introduce a new API version?
- When not to introduce a new API version?
- What is API contract?
- Which API versioning strategy should I use?
- Why is versioning REST APIs important?
- REST API Versioning Examples
- GitHub Example
- Summary: REST API Versioning
I've used these principles to increase my earnings by 63% in two years. So can you.
Dive into my 7 actionable steps to elevate your career.