Conception d'api REST

 Il y a une multitude de question quand nous commencons à convevoir un API rest. Un débat qui reviens souvent est les ressources imbriqués, parent / enfant, sous-ressource.

Hierachie

Pourquoi opter pour

/parents/{idParent}/enfants/{idEnfant}

au lieu de 

/enfants/{idEnfant}

 

La première approche peut être préférable si on veut montrer le lien hierarchique qui unit les ressources. Il faut cependant ne pas exagérer du niveau hierachique, car l'url peut rapidement devenir très long et rendre le tout moins lisible. Il est d'ailleurs rare de voir un api avec plus de 2 niveau.

Dans le deuxième cas, pour une sauvegarde, il faudrait que la ressource est le nom du parent.

Une autre approche serait

/parents/{idParent}?enfants={idEnfant}

 

Doublon

 

Rien n'empêche d'utilisé plusieurs approches, dans ce cas, on pourrait se retrouver dans le cas qu'il y a différent endpoint pour obtenir la même ressource.

 

Longueur des url

/companies/{idCompany}/departments/{idDepartment}/projects/{idProject}/employees

 

Il faut cependant ne pas exagérer du niveau hierachique, car l'url peut rapidement devenir très long et rendre le tout moins lisible. Il est d'ailleurs rare de voir un api avec plus de 2 niveau.

Changement de la relation

Avec une approche hierarchique,  s'il y a changement dans la relation dépendant si vous désirez continuer d'offrir la ressource ou non, il faudrat penser à utiliser le versionnement de votre api. Une redirection est aussi possible via en autre un api gateway

Sécurité

L'approche est une hierachie dévoile une relation entre les ressources qui pour dans certain casne pas être dévoilé.

Par exemple sur un site de rencontre

/users/{id}/pictures/

Il est possible qu'on ne veuille pas permettre à n'importe qui d'accéder à toutes les images d'une personne. Un autre niveau de sécurité peut être ajouté afin de permettre qu'a certain type d'utilisateur d'y accéder via par exemple la notion de rôle.

Il n'y a pas de bonne ou mauvaise approche, il faut juste connaitre les différentes possibilités et employé la méthode la plus adéquate pour nos besoins. N'oublier pas de bien documenter votre api par exemple avec un outil tel que spring-doc, swagger.

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