web-dev-qa-db-fra.com

Confusion entre le nom et le verbe dans les URL de repos

J'ai étudié sur Internet des API reposantes qui se concentrent sur les noms et non les verbes dans le modèle d'URL, mais maintenant je vois plusieurs liens qui utilisent des verbes dans l'URL.

Voici un exemple.

  • POST/v1/paiements/autorisation/<Authorization-Id>/capture
  • POST/v1/paiements/autorisation/<Authorization-Id>/void
  • POST/v1/paiements/autorisation/<Authorization-Id>/réautoriser

ce sont des apis Paypal. API Paypal

également sur wikipedia sur la page HTATEOAS ils ont donné un exemple;

<?xml version="1.0"?>
<account>
   <account_number>12345</account_number>
   <balance currency="usd">100.00</balance>
   <link rel="deposit" href="/account/12345/deposit" />
   <link rel="withdraw" href="/account/12345/withdraw" /> 
   <link rel="transfer" href="/account/12345/transfer" />
   <link rel="close" href="/account/12345/close" />
 </account>

lien: Wiki HATEOAS

Quelqu'un peut-il m'aider à clarifier ce point? pourquoi "capture", "vide", "dépôt", "retrait", "fermeture" sont dans l'URI parce qu'ils sont tous des verbes et non des noms?

ou est-ce correct d'utiliser ce genre de mots dans l'url des apis au repos complet?

restrestful-url
31
Uzair Xlade

Quelques extraits du REST API Design Rulebook sur différents types de ressources:

Document

Une ressource de document est un concept singulier qui s'apparente à une instance d'objet ou à un enregistrement de base de données.

Exemple: http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet

Collection

Une ressource de collection est un répertoire de ressources géré par le serveur. Les clients peuvent proposer de nouvelles ressources à ajouter à une collection. Cependant, c'est à la collection de choisir de créer ou non une nouvelle ressource.

Exemple: http://api.soccer.restapi.org/leagues/seattle/teams

Boutique

Un magasin est un référentiel de ressources géré par le client. Une ressource de magasin permet à un client API de placer des ressources, de les récupérer et de décider quand les supprimer. À eux seuls, les magasins ne créent pas de nouvelles ressources; par conséquent, un magasin ne génère jamais de nouveaux URI. Au lieu de cela, chaque ressource stockée a un URI qui a été choisi par un client lors de sa première mise en magasin.

Exemple: PUT /users/1234/favorites/alonso

Contrôleur

Une ressource contrôleur modélise un concept procédural. Les ressources du contrôleur sont comme des fonctions exécutables, avec des paramètres et des valeurs de retour; entrées et sorties.

Comme une application Web traditionnelle utilisant des formulaires HTML, une API REST s'appuie sur les ressources du contrôleur pour effectuer des actions spécifiques à l'application qui ne peuvent pas être mappées logiquement à l'une des méthodes standard (créer, récupérer, mettre à jour, et supprimer, également appelé CRUD).

Les noms de contrôleur apparaissent généralement comme le dernier segment d'un chemin URI, sans ressources enfants pour les suivre dans la hiérarchie.

Exemple: POST /alerts/245743/resend

Sur la base des définitions du livre, les URI que vous avez publiés relèvent probablement du type de ressource Controller , dont le livre indique plus tard:

Règle: Un verbe ou une expression verbale doit être utilisé pour les noms des contrôleurs

Exemples:

  • http://api.college.restapi.org/students/morgan/register
  • http://api.example.restapi.org/lists/4324/dedupe
  • http://api.ognom.restapi.org/dbs/reindex
  • http://api.build.restapi.org/qa/nightly/runTestSuite

Autres règles de dénomination, juste pour être complet

  • Règle: Un nom singulier doit être utilisé pour les noms de document
  • Règle: Un nom pluriel doit être utilisé pour les noms de collection
  • Règle: Un nom pluriel doit être utilisé pour les noms de magasins
21
Paul Samsotha

En REST, le verbe est la méthode HTTP. Dans votre exemple, il s'agit de POST mais il peut également s'agir de GET, PUT ou DELETE.

nom est la ressource identifiée par l'URL. Dans votre exemple, les "noms" sont /v1/payments/authorization/<Authorization-Id>/capture, etc.

Comme vous pouvez le voir, ce n'est pas vraiment un substantif puisque capture est un verbe: capturer une autorisation de paiement. Ce n'est pas RESTful car c'est une commande, un verbe, pas une chose, un substantif.

Une meilleure façon serait de modéliser ces commandes comme des choses comme /v1/payments/authorization/<Authorization-Id>/capturecommand. Cette commande serait une chose, un nom. Il pourrait indiquer, par exemple, s'il a réussi, quel a été le résultat, etc.

Il y a beaucoup de code qui prétend être RESTful et qui ne l'est pas.

7
user1907906

L'astuce consiste à en faire tous les noms (ou entités) qui fonctionnent avec les verbes CRUD.

Donc au lieu de;

POST /v1/payments/authorization/<Authorization-Id>/capture
POST /v1/payments/authorization/<Authorization-Id>/void
POST /v1/payments/authorization/<Authorization-Id>/reauthorize

Faites ceci;

capture -> POST /v1/payments/authorization/<Authorization-Id>
void    -> DELETE /v1/payments/authorization/<Authorization-Id>
reauthorize -> delete first then create again.
6
nesty