API REST Création de liens entre les collections de ressources

Question

J'ai réfléchi à la bonne méthode de définition des collections de ressources interdépendantes.

Par exemple, permet de considérer les « documents » et « commentaires » qui sont indépendamment accessibles via l'URI:

/documents/{doc-uri} 
/comments/{comment-id} 

Cependant, nous voulons généralement la collecte des commentaires relatifs à un document spécifique. Ce qui crée une question de conception sur la façon dont cela devrait être archétecté.

Je peux voir quelques options principales:

1.) Fournir une collection uri après le document uri pour commentaires

GET /documents/{doc-uri}/comments/ 

2.) Fournir un paramètre à la collection de commentaires pour sélectionner par document 3. Utiliser la négociation de contenu pour demander que les commentaires soient renvoyés via l'en-tête Accept.

// Get all the comments for a document 
GET /documents/{doc-uri} Accept: application/vnd.comments+xml 
// Create a new comment 
POST /documents/{doc-uri} Content-Type: application/vnd.comment+xml <comment>...</comment> 

Méthode 1 a l'avantage de mettre automatiquement les commentaires dans le contexte du document. Ce qui est également agréable lors de la création, la mise à jour et la suppression de commentaires en utilisant POST/PUT. Cependant, il n'offre pas un accès global aux commentaires en dehors du contexte d'un document. Donc, si nous voulions faire une recherche sur tous les commentaires dans le système, nous aurions besoin de la méthode n ° 2.

La méthode 2 offre plusieurs des mêmes avantages que le n ° 1, mais créer un commentaire sans le contexte d'un document n'a aucun sens. Puisque les commentaires doivent explicitement être liés à un document.

La méthode 3 est intéressante à partir d'une perspective GET et POST/create, mais elle devient un peu plus difficile avec la mise à jour et la suppression.

Je peux voir les avantages et les inconvénients de toutes ces méthodes, donc je suis à la recherche de plus de conseils de quelqu'un qui a peut-être approché et résolu ce problème auparavant.

Je considère faire les deux méthodes 1 & 2, ainsi je peux fournir toutes les fonctionnalités nécessaires, mais je suis inquiet que je puisse compliquer/dupliquer la fonctionnalité.

Answer 1

L'API REST doit être pilotée par hypermédia. Voir Hypermédia en tant que moteur de l'état de l'application (HATEOAS) contrainte. Donc, ne perdez pas votre temps sur URLPatterns, car ils ne sont pas RESTful. URLPattern implique un couplage étroit entre un client et un serveur; Simplement, le client doit être conscient de l'apparence des URL et avoir la capacité de les construire.

Tenir compte cette conception REST pour votre cas d'utilisation:

La représentation d'un document contient un lien où le client peut envoyer des messages ou des commentaires à l'utilisation de GET obtenir tous les commentaires sur le document. par exemple. Un client prend simplement cette URL et exécute la méthode GET ou POST sur l'URL; sans savoir comment l'URL est, ressemble.

Voir aussi ce message:

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

Answer 2

La combinaison des méthodes 1 et 2 semble bon, comme vous le dites dans la méthode 2, n'ont pas trop de sens de créer des commentaires sans un contexte de documents depuis un relation parent-enfant existe entre les deux, si vous supprimez un document est acceptable de supprimer tous ses commentaires aussi, vous pouvez rendre votre uri /comments/ une ressource en lecture seule afin d'éviter sa création sans document. Comme filip26 dit que repos apis devrait être hypermédia mais pas que les motifs d'url ne sont pas importants, vous pourriez avoir une ressource avec un uri ou plusieurs, si vos ressources ont plusieurs uris, c'est plus facile pour les clients de les trouver , l'inconvénient est que cela pourrait être déroutant car certains clients utilisent un uri plutôt qu'un autre, donc vous pouvez utiliser un uri canonique pour une ressource, quand un client accède à une ressource via cet uri canonique, vous pouvez renvoyer un 200 OK, quand une requête client l'un des autres uri vous pouvez renvoyer un 303 "Voir aussi" avec l'uri canonique. »