restVersioning

KO | EN

gitlite — search

#javascript #react #llm #golang #machine-learning #deep-learning #linux #nodejs #java #windows #cli #awesome-list #security #mcp

(★ 71)

Spring extension to route API calls to different methods based on a REST resource version

파일 탐색기

최종 버전 다운로드 (.zip)

.gitignore
pom.xml
README.md

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

#Spring REST versioning extension (POC)

This is a Spring extension that allows routing to different methods depending on the version of the resource that is
requested. This code is based on the suggestions from a Stack Overflow question I asked - [How to manage REST API versioning with
spring?](http://stackoverflow.com/questions/20198275/how-to-manage-rest-api-versioning-with-spring ).

##Approaches to manage versions
There are 2 main approaches to manage versions. One is to make the version explicit as part of the URL
(e.g. http://host.com/1.1/resource), but this goes against the purist view that a resource identifier, should be the
same regardless of the representation. The more *correct* approach is to use the Accept header to differentiate the
representation of the resource (version and format), for example calling http://host.com/resource with an Accept header
with the value application/vnd.app.resource-v1+json. The header mentions both the version and format expected.

Another aspect of versioning is whether to version each individual endpoint with a different version, or to version the
whole API (similar to what is done in programming APIs, in which when a new version is release, not all classes have 
changed).

This approach favours the idea that an API release increases the version on all endpoints (there's no need to change
annotation on all endpoints, but only on the endpoints that require the version increase). This removes the need from
clients to know exactly what version of each endpoint to call. This approach also allows, for more advanced clients, to
cherrypick which version of each endpoint to use.

## Code

Here's an example of how a controller looks like with this extension

```java
@Controller
@VersionedResource(media = "application/vnd.app.resource")
public class TestController {

@RequestMapping(value = {"/resource"}, method = RequestMethod.GET)
    @VersionedResource(from = "1.0", to = "1.0")
    @ResponseBody
    public Resource getResource_v1() {
        return new Resource("1.0");
    }

@RequestMapping(value = {"/resource"}, method = RequestMethod.GET)
    @VersionedResource(from = "2.0")
    @ResponseBody
    public Resource getResource_v2_onwards() {
        return new Resource("2.0");
    }
}
```

There are 2 main classes that used to extend spring `CustomRequestMappingHandlerMapping` and 
`VersionedResourceRequestCondition`. `CustomRequestMappingHandlerMapping` is the entry point of this extension and 
allows to to extend the default `RequestMappingHandlerMapping` in order to add a custom `RequestCondition`. 
`VersionedResourceRequestCondition` is responsible for figuring out if a controller method is a candidate to be invoked.

##Drawbacks of this implementation
1. Given that we need a custom `RequestMappingHandlerMapping`, instantiating it is non-trivial (see the 
`WebConfiguration` class) and there's a danger that this class will change in a follow up version of spring and might 
cause unexpected behaviour.
2. This implementation doesn't check for a version upper boundary in the `@VersionedResource` and also routes higher,
non-existent versions to methods without a version upper boundary 
(see `TestControllerTest.shouldReturnUnboundedVersionForCallToVersion32`).

##When is this approach a bad idea?
I think using versions on the URLs for public APIs is a better approach as the users might not be familiar with HTTP
(as an example Twitter and Facebook put the version on the URL). In these cases, making the API as simple as possible
to use is quite important.

restVersioning

파일 탐색기

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

restVersioning

파일 탐색기

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README