Par exemple, j'ai des entités: Client, Rapport. Le client peut avoir de nombreux rapports et je pense que le point de terminaison pour une seule gestion de rapport devrait être imbriqué comme ceci:
/clients/{client_id}/reports/{report_id}
Comme pour tous les rapports d'un client, le point final est attendu:
/clients/{client_id}/reports
Mais à quoi devrait ressembler un point de terminaison pour obtenir tous les rapports de tous les clients pour garder l'API cohérente et bien conçue.
Mes approches:
/clients/-/reports
Cela garde le format du point de terminaison le même, mais semble un peu inhabituel, ne peut trouver aucun rfc qui suggère cette façon.
/reports
Mais pour obtenir les rapports du client, c'est toujours:
/clients/{client_id}/reports
/reports?client={client_id}
- rapports d'un client
/reports
- rapports de tous les clients
En cas d'ajout d'un nouveau point de terminaison pour publier un rapport pour un client spécifique, il peut sembler laid, car ce sera une demande POST avec un paramètre dans l'URL.
Y a-t-il d'autres suggestions d'idées?
Mais à quoi devrait ressembler un point de terminaison pour obtenir tous les rapports de tous les clients pour garder l'API cohérente et bien conçue.
Avant toute chose, n'oubliez pas qu'il n'y a pas de règles d'or pour la modélisation des API RESTful. Tout ce que nous avons, ce sont des bonnes pratiques et des conventions. Cela étant dit, la réponse probable est, comme d'habitude, de choisir celle qui répond le mieux à vos besoins et dans ce cas celle qui exprime le mieux votre modèle.
Vérifiez donc les trois options de l'expressivité.
C'est une idée brillante. Il nous permet d'exprimer la condition tous les reports
qui appartiennent à clients
. Cela réduit la "requête" à un ensemble spécifique de rapports (ceux situés dans la limite clients
).
Il garde la notion de hiérarchie (appartenance) tout le temps, donc si reports
peut être trouvé à différents endroits, cette notation fait toute la différence. Par exemple:
/clients/-/reports
/departments/-/reports
/employees/-/reports
Cependant, pour récupérer tous les rapports disponibles dans le système, le maintien de la hiérarchie n'offre aucun avantage précieux par rapport à l'option suivante.
Si nous n'avons pas besoin d'exprimer limites/contextes/hiérarchie au moment de récupérer tous les rapports disponibles , cette approche me semble plus raisonnable.
Le nouvel URI (/reports
) laisse également ouverte la possibilité d'une gestion des rapports . Cependant, nous n'avons pas à lui fournir un support RESTful complet si nous ne le jugeons pas nécessaire. Par exemple, vous avez déclaré Make a separate endpoint just for all the reports
. C'est bien, vous n'avez qu'à implémenter GET
et peut-être quelques filtres pour les requêtes et c'est tout.
Notez que vous pouvez toujours le faire /reports?client={client_id}
. Avoir un URI différent pour la même ressource est bien. Certains articles que j'ai lus appelleraient cela robustesse.
J'ai l'impression que cette approche ne répond pas à vos attentes. De plus, je pense que cela vous amènera finalement au point de départ.
Notez que # 1 et # 2 ne s'excluent pas mutuellement. Nous pouvons implémenter les deux. Étant donné la situation réelle et selon les locaux du PO, je ne mettrais en œuvre que le n ° 2.
1: c'est équivalent à /clients/-/reports
J'imagine
Les modèles de conception d'API de Google suggèrent d'utiliser "-" dans ce scénario.
GET /clients/-/reports
La source:
https://cloud.google.com/apis/design/design_patterns#list_sub-collections