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.