la conception d'actions dans l'API REST - lorsque le repos de trop Reposante?

Je suis dans le processus de conception d'une API REST pour un projet sur lequel nous travaillons. C'est, je suis en train d'écrire le cahier des charges qui sera mis en œuvre plus tard.

Je vais avoir des ennuis à penser en noms propres/ressources au lieu de actions/les verbes. Sans entrer dans trop de projets spécifiques, nous écrivons une API autour de SVN. Par exemple, prendre les mesures qui valide les modifications sur le serveur SVN. Dans notre projet, nous avons de multiples définitions/versions de la validation de l'action:

  • simplement commettre de tous les fichiers modifiés
  • commettre une liste des fichiers modifiés (un sous-ensemble, au lieu de l'ensemble des fichiers modifiés)
  • ...

(1) Comment la conception de l'URL? La première question est, comment puis-je décrire la commit comme un nom/ressources au lieu d'un verbe?

Certains diront:

POST/PUT http://server.com/api/revision/commit

Devrait-il être un POST ou de vente? Je ne suis pas vraiment de la création d'un commettre des ressources, il n'est donc pas un POST. Cependant, je ne suis pas vraiment changer une commettre des ressources, il n'est donc pas un PUT. En fait, ce n'est pas un ressources, c'est un action. Une fois que l'action est exécutée, il a disparu, il n'y a pas de ressource pour être créé, modifié ou conservé pour référence ultérieure.

Cela dit, il doit être une ressource, de sorte que l'URL doit probablement être comme ce

POST http://server.com/api/revision/commitment

C'est également un POSTE, puisque nous sommes en créant un engagement. Nous ne sommes pas changer quoi que ce soit, donc pas de METTRE. Notez aussi que j'ai changé commettre en engagement, afin de refléter le fait que nous avons affaire à des ressources.

Cela fait-il sens? Pour moi, il ne fonctionne pas, il me pousse à la noix. Je veux exécuter une action, de ne pas créer une ressource qui ressemble à de l'action. Mais de toute façon.

Cela dit, pour aller plus loin, je viens de créer un engagement de ressources. Donc, logiquement, je devrais être capable de le récupérer plus tard:

GET http://server.com/api/revision/commitment/:id

Mais il n'y a aucun engagement de ressources! J'ai été forcé de faire un afin d'être paisible. tête explose

Alors, comment avez-vous vraiment spécifier les actions sur les ressources dans une API REST? Je ne parle pas le genre d'actions qui créent une ressource (créer un utilisateur, ...), mais sur le type d'actions qui manipulent une ressource ou d'un acte sur une ressource (commit révision, ...).

(2) Puis, d'autre part, dans le cas de la deuxième définition (voir ci-dessus), comment faire pour spécifier le sous-ensemble des fichiers modifiés? Par l'intermédiaire des paramètres ou dans une structure (par exemple tableau JSON) dans le CORPS? Qui est préférée? Existe-il des règles générales?

Merci à tous!

InformationsquelleAutor Appelsien S. | 2011-07-15
  1. 14

    Il est parfois plus facile de revenir en arrière une URL de conception que d'aller de l'avant. Il me semble que ce que vous appelez un "engagement" est en fait un révision lui-même. svn commit veut dire que, "s'il vous plaît accepter ces différences de ma actuellement à la révision sélectionnée en tant que nouveau (enfant) révision". Par conséquent, vous devez identifier qui est actuellement sélectionné révision (pour rester apatrides) et ensuite y ajouter de manière significative:

    POST http://server.com/api/revisions/16/children/

    Qui est, POSTE une entité qui encapsule les différences de révision 16. Le serveur peut alors réagir avec 201 Created, plus Location: /api/revisions/23/ (ou /api/revisions/16/children/1, qui redirige à l'ancienne).

    Alors, non seulement avez-vous prévu la création de nouvelles révisions, mais probablement aussi ajouté une liste utile de les enfants directs d'une révision.

    • Très utile commentaire. Je ne comprends pas ce que tu veux dire avec /enfants/ et /enfants/1. Pourriez-vous veuillez donner plus de détails? Quelle est la différence entre les révisions/x/enfants et de révisions/x/? Et entre /révisions/x/enfants/y /révisions/x/enfants/? Merci beaucoup.
    • La différence est dans les représentations. Par exemple, imaginez un GET sur /révisions/16/ renvoie des données au sujet de cette révision. Si il a 3 enfants, on pourrait s'attendre à ce que un OBTENIR sur /révisions/16/enfants/ doit retourner une liste de 3 URI, un pour chaque enfant. Alors un OBTENIR sur /révisions/16/enfants/2/ serait de retour pour la seconde de ces 3, ou, dans un système bien conçu, il vous rediriger vers un plus de l'URL canonique, comme /révisions/58/. Le point est de ne pas dupliquer les données à deux URL, à moins que vous ne se soucient pas d'eux de sortir de la synchronisation avec différentes copies mises en cache.
    InformationsquelleAutor fumanchu
  2. 2

    Arrêter de penser à des actions ;D

    Tout d'abord mettre votre SVN à base de fichiers, et ne repose pas sur une base de données, qui les aideront dans la pensée.

    Si vous pensez à ce sujet que vous n'avez que 3 de détente (en fait 4 peut-être) les opérations sur votre dépôt: svn add + svn commit de mettre un nouveau fichier dans la version controll. Cela se traduit par une mise sur le dossier dans lequel vous voulez ajouter et valider le fichier. svnroot:/projet/dossier en fait, comme les "id" du fichier est connu, vous pouvez le METTRE directement sur l'URL du fichier: svnroot:/projet/dossier/fichier.c

    Que vous souhaitez engager un changement, qui se traduit par un POST sur la ressource (pas le dossier, mais le fichier existant dans ce dossier). POST svnroot:/projet/dossier/fichier.c

    Si vous souhaitez supprimer un fichier, il obvioulsy est un DELETE.

    Si vous voulez savoir ce que le numéro de révision d'un certain fichier a utiliser d'ÉTAT.

    Commencer à penser en termes de ce qui se passe, pas de la façon dont les verbes sont appelés (co, ci, ajouter, mettre à jour, etc.), ce qui se passe c'est que les fichiers sont "créés" dans le référentiel, c'est une option de vente, ou modifié, c'est un POST ou supprimés ou retirés des thats une SUPPRESSION ou l'état est interrogée qui est l'ÉTAT.

    Si vous retrive le fichier, il est de toute évidence un GET.

    Donc, que ci-dessus est un actuall ressources existantes. Maintenant, vous pourriez commencer à inventer de plus de fonctionnalités, de donner le fichier d'une taille et d'un auteur ou du dernier commiter ou un message de commit! Maintenant, vous avez besoin de travailler sur les Url, pour laquelle aucune véritable ressource existe. Certains appellent cela des ressources virtuelles.

    Juste de rajouter "/auteurs", etc. à la fin de l'Url de ressource et de l'utilisation POST pour ajouter un auteur et d'apprendre à lire les auteurs. (Question de goût, vous pourriez utiliser les METTRE, serait peut-être plus propre d'après le RESTE de paradigme)

    InformationsquelleAutor Angel O'Sphere