API Versioning

API versioning is the practice of managing changes to an API and ensuring that these changes are made without disrupting clients. A good API versioning strategy clearly communicates the changes made and allows API consumers to decide when to upgrade to the latest version at their own pace.

Ways for API Versioning

There are multiple ways to version an API. Which one fits your needs best depends on your requirements and dependencies.

Considerations Which API Versioning to Choose

Costs

Additional costs can occur when multiple domains and SSL certificates are needed. Those costs usually occur for as long as an API version is maintained.

Rollout Time

In case an own domain is needed for each version, we need to take the registration time for the domain into consideration. This process can range from a few hours to some days.

Effort for Maintenance

Maintaining multiple versions of an API is always an extra effort. However, some approaches require more and some less maintenance efforts. The categories of efforts also change between different approaches. While, for example, a domain-based option takes more infrastructure effort, a header-based alternative might be more maintenance work for the business logic.

Complexity

The aspect of complexity includes considerations for the producer and the consumers of an API. Following best practices and standards helps reduce complexity and makes using an API more intuitive.

Flexibility

If users need to use functionality from different API versions, the used approach needs to be flexible for the clients that consume an API. In this context, the use of versioning via body and headers does make sense.

Caching

Usually, the default settings for caching include the path as a cache key. This means path-based API versioning already gets decent caching out of the box.

Control of User Experience

If we want to control the user experience, a managed version strategy is needed. Typically, this would happen via Feature Flags to enable or disable specific features. However, this approach can also be used for API versioning.

Scalability

Any control mechanism for API versioning that includes decent caching is always preferable to managed versions when it comes to scalability. The reason is that managed version most often needs some form of active component to decide for a user which API version to use.

Conclusion

The overview of API versioning compared to considerations serves as a helper for deciding which approach to use.

Path, query, and header-based API versioning are all decent options. I myself often use the path-based approach for the best results from caching and scalability, especially in Serverless environments.