API Versioning
How does API Versioning work?
API versioning is the process of making changes and updates to your API. It is an essential part of API management, and a good versioning strategy will allow updates to occur without disrupting the consumer experience. The aim is to steadily introduce new features, avoid large updates, and maintain functioning.
Why is versioning your API important? As an API evolves and develops, you will make changes and add new features. Even minor changes can have a domino effect and impact programs that use your API services. Such changes that could cause problems are called breaking changes.
What exactly are breaking changes? They could be removing a resource, changing a resource name, changing a resource data type, changing data format (e.g. JSON to XML), and more.
When should you version an API? It is considered best practice to versioning an API only when breaking changes are made. Non-breaking changes alone do not require versioning. Instead, they can be included in more major updates.
The first versioning method is called URI path versioning. With this method, the API version is included in the URI as v1, v2, v3, etc. This method is widely used and straightforward to implement, but it's important to keep previous versions active after new ones have been introduced.
The second method is query parameters. Similar to the URI path, the version is included in the URI, but as a query parameter. This method allows the version to be requested at the resource level. If no version is specified, you can default to the latest version.
The final method we'll look at is custom headers. In this method, the URI remains unchanged and the version number is set using a custom header in requests and responses. You can use the 'Accept-version' header followed by the version number.
Whichever method you choose, it's important to allow backward compatibility. This means keeping previous versions active not only as a backup in the case of breaking changes but also for users who decide to update in their own time.