Versionnement de son api rest

 Vous avez un ensemble d'api qui est utilisé par de multiple clients. De nouvelle fonctionnalités prévue vont changer les valeurs de retour et les paramètres de certaines méthode. Afin de ne pas casser l'existant, il est possible de mettre en place plusieurs versions des apis.

Nous verrons différentes approche pour mettre en place le versionnement d'un api.

Versionnement des entités, payload

Dans la première mise en place d'un api vous avez une entité  Person

Si vous devez ajouter un nouveau champs dans cette entité, l'ancienne pourrait être renommé PersonV1 et la nouvelle PersonV2. PersonV2 ayan un champ prenom

Versionnement des url

@RestController
public class PersonController {

  @GetMapping("v1/person")
  public PersonV1 personV1() {
    return new PersonV1("Collin");
  }

  @GetMapping("v2/person")
  public PersonV2 personV2() {
    return new PersonV2("Collin", "Marc");
  }

}

Versionnement par un RequestParam

@RestController
public class PersonController {

  @GetMapping(value="/person", params="v1)
  public PersonV1 personV1() {
    return new PersonV1("Collin");
  }

  @GetMapping(value="/person", params="v2")
  public PersonV2 personV2() {
    return new PersonV2("Collin", "Marc");
  } 

}

L'appel se ferait de cette façon


http://localhost:8080/person?v2

Versionnement par l'headers de la requête

@RestController
public class PersonController {

  @GetMapping(value="/person", headers="api-version=1)
  public PersonV1 personV1() {
    return new PersonV1("Collin");
  }

  @GetMapping(value="/person", headers="api-version=2")
  public PersonV2 personV2() {
    return new PersonV2("Collin", "Marc");
  } 

 } 

Si vous utilisez un outils tel que rester, postman, il faut ajouter dans la section headers la clé

api-version

et la valeur

1

Versionnement par le media type

@RestController
public class PersonController {

  @GetMapping(value="/person", produces="application/vnd.api-v1+json")
  public PersonV1 personV1() {
    return new PersonV1("Collin");
  }

  @GetMapping(value="/person", produces="application/vnd.api-v2+json")
  public PersonV2 personV2() {
    return new PersonV2("Collin", "Marc");
  } 

 } 

Le media type doit être mis le headers avec la clé Accept.

Plusieurs approches ont été spécifiés et tous ont un moins gros acteurs du marché utilise chacune de ses approches.

GitHub utilise le média type

Microsoft utilise le heders

Twitter utilise le url 

Amazon utilise le request param