Versioning Your REST API Made Easy: Tips and Tricks

Before we start, let’s talk a little bit about what is an API REST and why we should be careful about versioning.

Versioning REST API

When you have an API that multiple applications can consume, you should strongly consider using versioning on your APIs.

Example 1:

Let’s consider that your API is for a mobile application. If you do not support more than one version of your API, you will obligate the users to keep up with the latest version. In the case of a mobile app, this can be a bit annoying.

Example 2:

Let’s consider that your API is consumed for more than one service.
For example, you create a payment API that is used for more than one microservice. In this case, if you do not use versioning, it may cause break changes in all consumers.

This is why versioning your API is so important, by doing it, you can ensure that old consumers can still consume your API and have time to migrate to the latest version before it becomes unavailable.

Versioning Strategies

There is more than one way to version your REST API, let’s see some strategies and the advantages and disadvantages of each one.

URI

Advantages

• Clear and Explicit: Version numbers are directly visible in the URI, making it clear and explicit which version of the API is being accessed.

• Caching: URI versioning can leverage HTTP caching mechanisms effectively, as different versions of the API are treated as separate resources.

• Bookmarking: Consumers can bookmark specific versions of endpoints for future reference or sharing.

Disadvantages

• Pollution of URIs: Over time, URI versioning can lead to cluttered URIs, especially if multiple versions of the API are maintained simultaneously.

• Hard to Change: Once a version is included in the URI, it becomes part of the API's public contract and is difficult to change without breaking backward compatibility.

Example

• Twitter/X API: Twitter's REST API utilizes URI versioning by incorporating the API version number directly into the URI path. For example, https://api.twitter.com/1.1/statuses/user_timeline.json represents version 1.1 of the API.

• YouTube API utilizes URI versioning, allowing the clients to specify the API version using the “v” URI path. For example: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY&part=snippet,contentDetails,statistics,status this represents the version v3.

Header

Advantages

• Clean URIs: Versioning information is not included in the URI path, keeping URIs clean and focused on resource identification.

• Flexibility: Header versioning allows for more flexibility in API design, as version information is separate from the resource representation.

• Version Negotiation: Clients can negotiate the desired API version using HTTP headers, allowing for dynamic version selection based on client preferences or capabilities.

Disadvantages

• Less Discoverable: Versioning information is not directly visible in the request URI, which may make it less discoverable for developers.

• Dependency on Headers: Clients must include version information in request headers, which may require additional configuration or code changes.

Example

• GitHub API: The GitHub API supports header versioning. Clients can specify the desired API version using the X-GitHub-Api-Version header in HTTP requests. For example, X-GitHub-Api-Version:2022-11-28 indicates the version released on date 2022-11-28 of the GitHub API.

• Stripe API: Stripe's REST API allows clients to specify the API version using the Stripe-Version header in HTTP requests. This approach allows Stripe to introduce breaking changes in newer versions without impacting existing integrations.

Query Parameter

Advantages

• Non-Intrusive: Versioning information is included as a query parameter, which is non-intrusive and does not clutter the URI path.

• Easy to Implement: Adding version information as a query parameter is straightforward and does not require significant changes to existing API endpoints.

Disadvantages

• Caching Challenges: Query parameter versioning can lead to caching challenges, as different versions of the same resource may be cached separately.

• Potential for Complexity: Handling versioning logic in query parameters can introduce complexity, especially for complex APIs with numerous endpoints.

• Discoverability: Versioning information is not directly visible in the URI path, which may impact discoverability for developers exploring the API.

Example

• Azure Media Services API: this API utilizes query parameter versioning for the version of the API it refers to. For example, https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Media/mediaservices/{accountName}/liveEvents/{liveEventName}?api-version=2022-11-01

Conclusion

There are many ways to version your REST API, the most famous is using URI and Header, it is essential to decide on one way and keep it clear for the consumers.

It is also important to keep your documentation up to date and notify consumers that a new version exists, as well as the deadline for removing the old version, giving consumers enough time to update to the latest version.

I hope this can help you guarantee that your APIs are backward compatible.

If this helped you, subscribe to continue receiving more useful content 😊

References

• Github API Versions

• Stripe - Versioning

• Twitter API

• YouTube API Data

• Azure Media Services API