I wrote a short poem that explains the need for API versioning:
There was an API
And it was good
Then PM came
And said you should
Change the field
From array to string
How can I do it?
This is BC!
And there it comes
The magical V
V like a version
Of your API
Lets get into the details!
Why and when to version an API?
I believe almost everyone once asked themselves the question Should I version the API I created?. Almost like always, theres no single answer. However, if you already thought about it, it might be a good idea to pay attention to the problem before it becomes a real production issue.
From my experience, all the APIs that work directly with the client (mobile apps, web applications) should be versioned. Imagine that you want to perform a breaking change like in the poem: the API supports multiple categories per item, but customers don't like it for some reason. The business comes and asks you to change the API so it always accepts only a single category. If you change the API in place you'll break all the clients that already use the current solution. For the web application there could probably be a short time while it stops working (for the time of deployment), but how can you force the users to upgrade all the mobile apps at once?
On the other hand, if your API is internal you might not need full API versioning. Sometimes it'll be easier to introduce a copy-paste endpoint, switch the usage on the clients side, and then remove the old one. This approach requires you to know exactly how many clients the API has and align with all the consumers beforehand.
How to version the API?
There are several approaches to API versioning that can be used. I believe the most common are described below.
Versioning via URL path param
The idea is to introduce the API version as a part of the path for each request coming to your API. The main issue with this solution is that for each new version of the APIs you need to modify your API specification for all endpoints to change the URL. I believe it can be pretty messy in the long run.
Versioning via URL query param
The approach is similar, but this time your application will need to parse and look for specific query path parameters for each request coming to the application. It might not be a big issue on the server side, but from the mobile/frontend side it might be a bit tricky to implement this solution, especially if there are endpoints that already use the query params to fetch data (like pagination). Usually, the clients use some kind of generator to not write all the code manually, and those will not support this kind of versioning without additional effort.
Versioning by extending the Accept header content
Accept: text/json; version=1
This idea is about appending a version string to the existing Accepts header. I don't personally like this solution for similar reasons as with the URL query param. I believe that it might not be so straightforward on the client side to modify the Accept header for each request - they are usually automatically populated by the HTTP client based on the passed content type.
Versioning through the custom header
Accept-Version: 1.0
The idea is to add a custom header to every request. This is in my opinion the best and clearest approach that Ill show you how to implement in the Spring Boot application.
Versioning through the custom headerSpring Boot configuration
To achieve the goal we need to add several small classes to the project, that will allow us to easily define the same endpoints across different controllers (or even the same) being identified by the custom annotation were going to create.
First of all, we need to define the custom annotation and enum with supported API versions:
https://gist.github.com/marrek13/23f5026f210e7dbdff8a318ce8f3beec
Then we need to write ApiVersionCondition class that implements the Spring RequestCondition interface. It requires implementing 3 methods:
combine defines the rules of overriding the annotations between classes and methods. In this case method annotations takes precedence over class annotations.
getMatchingCondition is responsible for reading the API version from the request and comparing it with the API version set in the annotation. We also fall back to version 1.0.0 if the request doesn't contain the Accept-version header. Another possibility is to always require the header and return null when its not present.
compareTo is used to define version order. In our case, its an enum so its compareTo method is used.
https://gist.github.com/marrek13/89fc75d0cb2323b7ca0c9b3d8a91bafd
The next step is to extend the Spring RequestMappingHandlerMapping class that will tell spring how to create the ApiVersionCondition for classes and methods. This time we need to override 2 methods:
getCustomMethodCondition defines how to create the ApiVersionCondition from a Method
getCustomTypeCondition defines how to create the ApiVersionCondition from a Class
https://gist.github.com/marrek13/431ef4041730ddb985920baf154e3117
And the last step before we can start using the annotation in the controllers is to add the new RequestMappingHandlerMapping class to the Spring Boot Configuration
https://gist.github.com/marrek13/a446cc08a4f99d991079a57d47dd4162
Using the new annotation in controllers
Lets create 3 classes for testing purposes. We have 1 API interface and 2 implementations for different API versions. We create the 1.0.0 version annotation on the V1 controller and the 2.0.0 annotation on the V2 controller with the 2.1.0 annotation of one of its methods.
Color API interface
https://gist.github.com/marrek13/2722506542a473133ad10a4ba3d3f6c7
V1.0.0 controller
https://gist.github.com/marrek13/1820bb97ac58fe4efaf8d5e880bb59bd
V2.0.0 controller with one V2.1.0 method
https://gist.github.com/marrek13/aac7dc877c83dd6840b969d4ab1a4788
Results for different curl calls
Calling list endpoint without version header or with 1.0.0 version returns the V1.0.0 controller response:
curl --location --request GET 'http://localhost:8080/colors'
curl --location --request GET 'http://localhost:8080/colors' --header 'Accept-version: 1.0.0'
Response:
[
{
"tag": "V1.0.0 list color",
"hex": "#FF0000"
}
]
Calling list endpoint with 2.0.0 or 2.1.0 version header returns V2.0.0 controller response:
curl --location --request GET 'http://localhost:8484/colors' --header 'Accept-version: 2.0.0'
curl --location --request GET 'http://localhost:8484/colors' --header 'Accept-version: 2.1.0'
Response:
{
"colors": [
{
"tag": "V2.0.0 list color",
"hex": "#f0f0f0"
}
]
}
Calling single item endpoint without version header or with 1.0.0/2.0.0 returns V1.0.0 controller value:
curl --location --request GET 'http://localhost:8484/color'
curl --location --request GET 'http://localhost:8484/color' --header 'Accept-version: 1.0.0'
curl --location --request GET 'http://localhost:8484/color' --header 'Accept-version: 2.0.0'
Response:
{
"tag": "V1.0.0 single color",
"hex": "#FF0000"
}
Finally calling single item endpoint with 2.1.0 version header returns V2.1.0 controller method value
curl --location --request GET 'http://localhost:8484/color' --header 'Accept-version: 2.1.0'
Response:
{
"tag": "V2.1.0 single color",
"hex": "#f0f0f0"
}
Performance impact
Last thing to check is the impact on application performance. For that purpose I used Apache Benchmark. I ran a test that calls the endpoint 10000 times with no concurrent users:
ab -n 100000 -c 1 -H "Accept-version: 2.0.0" http://localhost:8484/colors
The first test I ran with the @ApiVersion annotation processor enabled :
Concurrency Level: 1
Time taken for tests: 95.117 seconds
Complete requests: 100000
Failed requests: 0
Total transferred: 16800000 bytes
HTML transferred: 4000000 bytes
Requests per second: 1051.33 [#/sec] (mean)
Time per request: 0.951 [ms] (mean)
Time per request: 0.951 [ms] (mean, across all concurrent requests)
Transfer rate: 172.48 [Kbytes/sec] received
Then I removed all the configs and annotations we created and I left only one controller which I tested with the same command:
Concurrency Level: 1
Time taken for tests: 82.624 seconds
Complete requests: 100000
Failed requests: 0
Total transferred: 16800000 bytes
HTML transferred: 4000000 bytes
Requests per second: 1210.30 [#/sec] (mean)
Time per request: 0.826 [ms] (mean)
Time per request: 0.826 [ms] (mean, across all concurrent requests)
Transfer rate: 198.57 [Kbytes/sec] received
The result is that the annotation processor has some impact on the requests but the mean impact per request is only 1/8 ms. I think this is acceptable value and will matter only in performance-critical environments.
I hope this will help you to manage the API versions in your code easier and will make your code architecture cleaner. Happy to hear any feedback from you!
Top comments (0)