Comment gérer les API REST de gestion des versions avec le printemps?

Je viens de créer une solution personnalisée. Je suis à l'aide de la @ApiVersion annotation en combinaison avec @RequestMapping annotation à l'intérieur de @Controller classes.

Exemple:

@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

}

Mise en œuvre:

ApiVersion.java annotation:

@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiVersion {
    int[] value();
}

ApiVersionRequestMappingHandlerMapping.java (ce qui est surtout copier et coller à partir 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 dans WebMvcConfigurationSupport:

public class WebMvcConfig extends WebMvcConfigurationSupport {
@Override
public RequestMappingHandlerMapping requestMappingHandlerMapping() {
return new ApiVersionRequestMappingHandlerMapping("v");
}
}

J'ai mis en œuvre une solution qui gère PARFAITEMENT le problème avec le repos de contrôle de version.

D'une manière générale, il existe 3 méthodes principales pour le repos versions:

• Cheminbasée sur approche, dans laquelle le client définit la version dans l'URL:

  http://localhost:9001/api/v1/user
  http://localhost:9001/api/v2/user

• Content-Type en-tête, dans lequel le client définit la version en Accepter en-tête:

  http://localhost:9001/api/v1/user with 
  Accept: application/vnd.app-1.0+json OR application/vnd.app-2.0+json

• En-Tête personnalisé, dans lequel le client définit la version de dans un en-tête personnalisé.

La problème avec le première approche est que si vous modifiez la version disons à partir de v1 -> v2, vous avez probablement besoin de copier-coller le v1 ressources qui n'ont pas changé de v2 chemin

La problème avec le deuxième approche est que certains outils comme http://swagger.io/ ne peut pas distincte entre les opérations avec le même chemin, mais les différents Type de Contenu (vérifier la question https://github.com/OAI/OpenAPI-Specification/issues/146)

La solution

Depuis que je travaille beaucoup avec le reste des outils de documentation, je préfère utiliser de la première approche. Ma solution gère le problème avec la première approche, de sorte que vous n'avez pas besoin de copier-coller l'extrémité de la nouvelle version.

Disons que nous avons des versions v1 et v2 pour l'Utilisateur contrôleur:

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";
}
}

La exigence est que si je demande le v1 pour la ressource de l'utilisateur-je prendre le "Utilisateur V1" repsonse, sinon, si je demande à la v2, v3 et ainsi de suite je dois prendre le "de l'Utilisateur V2" réponse.

Pour mettre en œuvre ce printemps, nous avons besoin de remplacer la valeur par défaut RequestMappingHandlerMapping comportement:

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 ;
}

}

La mise en œuvre se lit la version dans l'URL et lui demande de printemps pour résoudre l'URL .Dans le cas où cette URL n'existe (par exemple, le client a demandé v3) ensuite, nous avons essayer avec v2 et ainsi de un jusqu'à ce que nous trouvons la plus récente version de la ressource.

Afin de voir les avantages de cette mise en œuvre, disons que nous avons deux ressources: l'Utilisateur et l'Entreprise:

http://localhost:9001/api/v{version}/user
http://localhost:9001/api/v{version}/company

Disons que nous avons fait un changement de société "contrat" qui rompt le client. Nous avons donc mettre en œuvre les http://localhost:9001/api/v2/company et nous vous demandons de client à changer de v2 plutôt que sur la v1.

De sorte que le nouveau demandes de client sont les suivantes:

http://localhost:9001/api/v2/user
http://localhost:9001/api/v2/company

au lieu de:

http://localhost:9001/api/v1/user
http://localhost:9001/api/v1/company

La meilleur partie ici, c'est qu'avec cette solution, le client devra obtenir les informations de l'utilisateur à partir de v1 et de la société de l'information à partir de v2 sans la nécessité pour créer un nouveau (même) d'extrémité de l'utilisateur v2!

Reste De La Documentation
Comme je l'ai dit avant que la raison pour laquelle j'sélectionnez l'URL de base de gestion des versions approche est que certains outils comme swagger n'document différemment les points de terminaison avec la même URL mais différents type de contenu. Avec cette solution, les deux points sont affichés depuis différentes URL:

GIT

Solution mise en œuvre au:
https://github.com/mspapant/restVersioningExample/

Ce propos pour l'utilisation de l'héritage pour le modèle de contrôle de version? C'est ce que j'utilise dans mon projet et il ne requiert pas de configuration spring et me fait exactement ce que je veux.

@RestController
@RequestMapping(value = "/test/1")
@Deprecated
public class Test1 {
...Fields Getters Setters...
@RequestMapping(method = RequestMethod.GET)
@Deprecated
public Test getTest(Long id) {
return serviceClass.getTestById(id);
}
@RequestMapping(method = RequestMethod.PUT)
public Test getTest(Test test) {
return serviceClass.updateTest(test);
}
}
@RestController
@RequestMapping(value = "/test/2")
public class Test2 extends Test1 {
...Fields Getters Setters...
@Override
@RequestMapping(method = RequestMethod.GET)
public Test getTest(Long id) {
return serviceClass.getAUpdated(id);
}
@RequestMapping(method = RequestMethod.DELETE)
public Test deleteTest(Long id) {
return serviceClass.deleteTestById(id);
}
}

Cet ensemble permet à peu de la duplication de code et la possibilité de remplacer les méthodes dans les nouvelles versions de l'api avec peu de travail. Il enregistre également le besoin de compliquer votre code source avec la version de commutation de la logique. Si vous n'avez pas de code d'un point de terminaison dans une version, il va saisir la précédente version par défaut.

Par rapport à ce que font les autres, cela semble plus facile. Est-il quelque chose que je suis absent?

J'ai déjà essayé à ma version de l'API à l'aide de la URI Versioning, comme:

/api/v1/orders
/api/v2/orders

Mais il y a certains défis en essayant de faire ce travail: comment organiser votre code avec des versions différentes? Comment gérer les deux (ou plus) des versions en même temps? Quel est l'impact lors de la suppression d'une version?

La meilleure alternative que j'ai trouvé n'était pas la version de l'ensemble de l'API, mais de contrôle de la version sur chaque extrémité. Ce modèle est appelé Gestion des versions à l'aide d'en-tête Accept ou Gestion des versions à travers la négociation de contenu:

Cette approche nous permet de version d'une ressource unique représentation
au lieu de versioning l'ensemble de l'API, qui nous donne une plus granulaire
contrôle sur la gestion des versions. Il crée également une plus petite empreinte dans le
base de code que nous n'avons pas à fourche de l'ensemble de l'application lors de l'
la création d'une nouvelle version. Un autre avantage de cette approche est qu'il
ne nécessite pas la mise en œuvre de URI règles de routage introduit par
gestion des versions à travers le chemin de l'URI.

Mise en œuvre sur le Printemps

D'abord, vous créez un Contrôleur avec un produit de base de l'attribut, qui sera appliqué par défaut pour chaque paramètre à l'intérieur de la classe.

@RestController
@RequestMapping(value = "/api/orders/", produces = "application/vnd.company.etc.v1+json")
public class OrderController {
}

Après cela, créer un scénario où vous avez deux versions d'un point de terminaison pour créer un bon de commande:

@Deprecated
@PostMapping
public ResponseEntity<OrderResponse> createV1(
@RequestBody OrderRequest orderRequest) {
OrderResponse response = createOrderService.createOrder(orderRequest);
return new ResponseEntity<>(response, HttpStatus.CREATED);
}
@PostMapping(
produces = "application/vnd.company.etc.v2+json",
consumes = "application/vnd.company.etc.v2+json")
public ResponseEntity<OrderResponseV2> createV2(
@RequestBody OrderRequestV2 orderRequest) {
OrderResponse response = createOrderService.createOrder(orderRequest);
return new ResponseEntity<>(response, HttpStatus.CREATED);
}

Fait! Appelez simplement chaque extrémité à l'aide de l'souhaité en-Tête Http version:

Content-Type: application/vnd.company.etc.v1+json

Ou, pour appeler la version deux:

Content-Type: application/vnd.company.etc.v2+json

Au sujet de vos inquiétudes:

Et depuis pas toutes les méthodes de l'API de changement dans le même communiqué, je
ne veux pas aller à chacun de mes contrôleurs et de changer quoi que ce soit pour un
gestionnaire qui n'a pas changé entre les versions

Comme l'a expliqué, cette stratégie s'appuie sur chaque Contrôleur et le point de terminaison avec sa version actuelle. Vous modifiez uniquement le point de terminaison qui ont des modifications et des besoins d'une nouvelle version.

Et l'Arrogance?

Installation de l'Aisance avec les différentes versions est également très facile à l'aide de cette stratégie. Voir cette réponse pour plus de détails.