How to manage REST API versioning with spring?
I just created a custom solution. I'm using the @ApiVersion annotation in combination with @RequestMapping annotation inside @Controller classes.
Example:
@Controller
@RequestMapping("x")
@ApiVersion(1)
class MyController {
@RequestMapping("a")
void a() {} // maps to /v1/x/a
@RequestMapping("b")
@ApiVersion(2)
void b() {} // maps to /v2/x/b
@RequestMapping("c")
@ApiVersion({1,3})
void c() {} // maps to /v1/x/c
// and to /v3/x/c
}
Implementation:
ApiVersion.java annotation:
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiVersion {
int[] value();
}
ApiVersionRequestMappingHandlerMapping.java (this is mostly copy and paste from RequestMappingHandlerMapping):
public class ApiVersionRequestMappingHandlerMapping extends RequestMappingHandlerMapping {
private final String prefix;
public ApiVersionRequestMappingHandlerMapping(String prefix) {
this.prefix = prefix;
}
@Override
protected RequestMappingInfo getMappingForMethod(Method method, Class<?> handlerType) {
RequestMappingInfo info = super.getMappingForMethod(method, handlerType);
if(info == null) return null;
ApiVersion methodAnnotation = AnnotationUtils.findAnnotation(method, ApiVersion.class);
if(methodAnnotation != null) {
RequestCondition<?> methodCondition = getCustomMethodCondition(method);
// Concatenate our ApiVersion with the usual request mapping
info = createApiVersionInfo(methodAnnotation, methodCondition).combine(info);
} else {
ApiVersion typeAnnotation = AnnotationUtils.findAnnotation(handlerType, ApiVersion.class);
if(typeAnnotation != null) {
RequestCondition<?> typeCondition = getCustomTypeCondition(handlerType);
// Concatenate our ApiVersion with the usual request mapping
info = createApiVersionInfo(typeAnnotation, typeCondition).combine(info);
}
}
return info;
}
private RequestMappingInfo createApiVersionInfo(ApiVersion annotation, RequestCondition<?> customCondition) {
int[] values = annotation.value();
String[] patterns = new String[values.length];
for(int i=0; i<values.length; i++) {
// Build the URL prefix
patterns[i] = prefix+values[i];
}
return new RequestMappingInfo(
new PatternsRequestCondition(patterns, getUrlPathHelper(), getPathMatcher(), useSuffixPatternMatch(), useTrailingSlashMatch(), getFileExtensions()),
new RequestMethodsRequestCondition(),
new ParamsRequestCondition(),
new HeadersRequestCondition(),
new ConsumesRequestCondition(),
new ProducesRequestCondition(),
customCondition);
}
}
Injection into WebMvcConfigurationSupport:
public class WebMvcConfig extends WebMvcConfigurationSupport {
@Override
public RequestMappingHandlerMapping requestMappingHandlerMapping() {
return new ApiVersionRequestMappingHandlerMapping("v");
}
}
I would still recommend using URL's for versioning because in URLs @RequestMapping supports patterns and path parameters, which format could be specified with regexp.
And to handle client upgrades (which you mentioned in comment) you can use aliases like 'latest'. Or have unversioned version of api which uses latest version (yeah).
Also using path parameters you can implement any complex version handling logic, and if you already want to have ranges, you very well might want something more soon enough.
Here is a couple of examples:
@RequestMapping({
"/**/public_api/1.1/method",
"/**/public_api/1.2/method",
})
public void method1(){
}
@RequestMapping({
"/**/public_api/1.3/method"
"/**/public_api/latest/method"
"/**/public_api/method"
})
public void method2(){
}
@RequestMapping({
"/**/public_api/1.4/method"
"/**/public_api/beta/method"
})
public void method2(){
}
//handles all 1.* requests
@RequestMapping({
"/**/public_api/{version:1\\.\\d+}/method"
})
public void methodManual1(@PathVariable("version") String version){
}
//handles 1.0-1.6 range, but somewhat ugly
@RequestMapping({
"/**/public_api/{version:1\\.[0123456]?}/method"
})
public void methodManual1(@PathVariable("version") String version){
}
//fully manual version handling
@RequestMapping({
"/**/public_api/{version}/method"
})
public void methodManual2(@PathVariable("version") String version){
int[] versionParts = getVersionParts(version);
//manual handling of versions
}
public int[] getVersionParts(String version){
try{
String[] versionParts = version.split("\\.");
int[] result = new int[versionParts.length];
for(int i=0;i<versionParts.length;i++){
result[i] = Integer.parseInt(versionParts[i]);
}
return result;
}catch (Exception ex) {
return null;
}
}
Based on the last approach you can actually implement something like what you want.
For example you can have a controller that contains only method stabs with version handling.
In that handling you look (using reflection/AOP/code generation libraries) in some spring service/component or in the same class for method with the same name/signature and required @VersionRange and invoke it passing all parameters.
I have implemented a solution which handles PERFECTLY the problem with rest versioning.
General Speaking there are 3 major approaches for rest versioning:
Path-based approch, in which the client defines the version in URL:
http://localhost:9001/api/v1/user http://localhost:9001/api/v2/userContent-Type header, in which the client defines the version in Accept header:
http://localhost:9001/api/v1/user with Accept: application/vnd.app-1.0+json OR application/vnd.app-2.0+jsonCustom Header, in which the client defines the version in a custom header.
The problem with the first approach is that if you change the version let's say from v1 -> v2, probably you need to copy-paste the v1 resources that haven't changed to v2 path
The problem with the second approach is that some tools like http://swagger.io/ cannot distinct between operations with same path but different Content-Type (check issue https://github.com/OAI/OpenAPI-Specification/issues/146)
The solution
Since i am working a lot with rest documentation tools, i prefer to use the first approach. My solution handles the problem with the first approach, so you don't need to copy-paste the endpoint to the new version.
Let's say we have v1 and v2 versions for the User controller:
package com.mspapant.example.restVersion.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
/**
* The user controller.
*
* @author : Manos Papantonakos on 19/8/2016.
*/
@Controller
@Api(value = "user", description = "Operations about users")
public class UserController {
/**
* Return the user.
*
* @return the user
*/
@ResponseBody
@RequestMapping(method = RequestMethod.GET, value = "/api/v1/user")
@ApiOperation(value = "Returns user", notes = "Returns the user", tags = {"GET", "User"})
public String getUserV1() {
return "User V1";
}
/**
* Return the user.
*
* @return the user
*/
@ResponseBody
@RequestMapping(method = RequestMethod.GET, value = "/api/v2/user")
@ApiOperation(value = "Returns user", notes = "Returns the user", tags = {"GET", "User"})
public String getUserV2() {
return "User V2";
}
}
The requirement is if i request the v1 for the user resource i have to take the "User V1" repsonse, otherwise if i request the v2, v3 and so on i have to take the "User V2" response.
In order to implement this in spring, we need to override the default RequestMappingHandlerMapping behavior:
package com.mspapant.example.restVersion.conf.mapping;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.method.HandlerMethod;
import org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletRequestWrapper;
public class VersionRequestMappingHandlerMapping extends RequestMappingHandlerMapping {
@Value("${server.apiContext}")
private String apiContext;
@Value("${server.versionContext}")
private String versionContext;
@Override
protected HandlerMethod lookupHandlerMethod(String lookupPath, HttpServletRequest request) throws Exception {
HandlerMethod method = super.lookupHandlerMethod(lookupPath, request);
if (method == null && lookupPath.contains(getApiAndVersionContext())) {
String afterAPIURL = lookupPath.substring(lookupPath.indexOf(getApiAndVersionContext()) + getApiAndVersionContext().length());
String version = afterAPIURL.substring(0, afterAPIURL.indexOf("/"));
String path = afterAPIURL.substring(version.length() + 1);
int previousVersion = getPreviousVersion(version);
if (previousVersion != 0) {
lookupPath = getApiAndVersionContext() + previousVersion + "/" + path;
final String lookupFinal = lookupPath;
return lookupHandlerMethod(lookupPath, new HttpServletRequestWrapper(request) {
@Override
public String getRequestURI() {
return lookupFinal;
}
@Override
public String getServletPath() {
return lookupFinal;
}});
}
}
return method;
}
private String getApiAndVersionContext() {
return "/" + apiContext + "/" + versionContext;
}
private int getPreviousVersion(final String version) {
return new Integer(version) - 1 ;
}
}
The implementation reads the version in the URL and asks from spring to resolve the URL .In case this URL does not exists (for example the client requested v3) then we try with v2 and so one until we find the most recent version for the resource.
In order to see the benefits from this implementation, let's say we have two resources: User and Company:
http://localhost:9001/api/v{version}/user
http://localhost:9001/api/v{version}/company
Let's say we made a change in company "contract" that breaks the client. So we implement the http://localhost:9001/api/v2/company and we ask from client to change to v2 instead on v1.
So the new requests from client are:
http://localhost:9001/api/v2/user
http://localhost:9001/api/v2/company
instead of:
http://localhost:9001/api/v1/user
http://localhost:9001/api/v1/company
The best part here is that with this solution the client will get the user information from v1 and company information from v2 without the need to create a new (same) endpoint from user v2!
Rest Documentation As i said before the reason i select the URL-based versioning approach is that some tools like swagger do not document differently the endpoints with the same URL but different content type. With this solution, both endpoints are displayed since have different URL:
GIT
Solution implementation at: https://github.com/mspapant/restVersioningExample/
Regardless whether versioning can be avoided by doing backwards compatible changes (which might not always possible when you are bound by some corporate guidelines or your API clients are implemented in a buggy way and would break even if they should not) the abstracted requirement is an interesting one:
How can I do a custom request mapping that does arbitrary evaluations of header values from the request without doing the evaluation in the method body?
As described in this SO answer you actually can have the same @RequestMapping and use a different annotation to differentiate during the actual routing that happens during runtime. To do so, you will have to:
- Create a new annotation
VersionRange. - Implement a
RequestCondition<VersionRange>. Since you will have something like a best-match algorithm you will have to check whether methods annotated with otherVersionRangevalues provide a better match for the current request. - Implement a
VersionRangeRequestMappingHandlerMappingbased on the annotation and request condition (as described in the post How to implement @RequestMapping custom properties ). - Configure spring to evaluate your
VersionRangeRequestMappingHandlerMappingbefore using the defaultRequestMappingHandlerMapping(e.g. by setting its order to 0).
This wouldn't require any hacky replacements of Spring components but uses the Spring configuration and extension mechanisms so it should work even if you update your Spring version (as long as the new version supports these mechanisms).