Question Actions REST et considérations relatives à la conception de l'API URL


Je construis un système de gestion des stocks et je suis occupé à concevoir (penser) l'API et mon implémentation REST.

J'ai les ressources suivantes et sur la ressource, vous pouvez effectuer de nombreuses actions / opérations. Chaque opération modifiera la ressource et dans certains cas, créera une nouvelle ressource et créera également un historique ou des transactions.

Je suis à la recherche de commentaires d'experts sur la facilité d'utilisation et l'acceptabilité en ce qui concerne la conception des URL et des ressources. Les pièges et les exemples réels, toute opinion ou critique sont les bienvenues.

Mes inquiétudes sont que l'application entière pourrait être développée autour de cette grande ressource? Ma pile backend sera un framework C # et servicestack et pour le frontend j'utiliserai HTML et AngularJS. Pas que ça fasse une différence.

Scénario 1. Opération typique sera:

POST /inventory/{id}/move
POST /inventory/{id}/scrap
PUT  /inventory/{id}/takeon
POST /inventory/{id}/pick
PUT  /inventory/{id}/receive
POST /inventory/{id}/hold
POST /inventory/{id}/release
POST /inventory/{id}/transfer
POST /inventory/{id}/return
POST /inventory/{id}/adjustment


{
  "userID": "",       //who is doing the actions (all)
  "tolocationID": "", //new location for inventory (move/takeon/pick/receive/transfer/return)
  "qty": "",          //qty (pick/receive/takeon/transfer/return)
  "comment": "",      //optional for transaction (all)
  "serial": "",       //(takeon/receive)
  "batch": "",        //(takeon/receive)
  "expirydate": "",   //(takeon/receive)
  "itemCode": "",     //(takeon/receive)
  "documentID": "",   //(pick/receive/return/transfer)
  "reference" :"",    //(all)
  "UOM" :"",          //(all)
  "reference" :"",    //(all)
}

Est-ce acceptable en ce qui concerne les normes. L'autre approche pourrait être.

Scénario 2.

POST /inventory/{id}/move
POST /inventory/{id}/scrap
PUT  /inventory/{id}/takeon
POST /document/{id}/pick     //**document**
PUT  /document/{id}/receive  //**document**
POST /inventory/{id}/hold
POST /inventory/{id}/release
POST /document/{id}/transfer  //**document**
POST /document/{id}/return    //**document**
POST /inventory/{id}/adjustment

et ensuite pour changer les ressources.

Scénario 3. À mon avis, mal

POST /transaction/move/{...}
POST /transaction/scrap/{...}
PUT  /transaction/takeon/{...}
POST /transaction/pick/{...}  
PUT  /transaction/receive/{...} 
POST /transaction/hold/{...}
POST /transaction/release/{...}
POST /transaction/transfer/{...}  
POST /transaction/return/{...}
POST /transaction/adjustment/{...}

Tous les commentaires sont les bienvenus, sans chercher de réponse, mais plus de conseils sur les considérations de conception?

Merci d'avoir pris le temps de lire cette entrée!


32
2017-08-13 13:39


origine


Réponses:


J'ai les ressources suivantes et sur la ressource que vous pouvez effectuer   nombreuses actions / opérations. Chaque opération modifiera la ressource et   dans certains cas, créer une nouvelle ressource et également créer un historique ou   transactions.

L'idée d'utiliser les verbes HTTP comme verbe unique, sans inclure les verbes dans vos URL, est fondamentale pour le schéma d'architecture REST. Dans vos chaussures, je voudrais envisager de retravailler votre système pour supprimer les verbes. Il est difficile de suggérer un design sans vraiment savoir ce que signifient les verbes, mais peut-être quelque chose de plus proche de:

GET /inventory/{id}
PUT /inventory/{id} -- update with new location 
PUT /inventory/{id} -- update with new status (scrapped)

etc .. C'est une approche plus RESTful. Bon nombre de ces actions semblent être uniquement des PUT qui mettent à jour plusieurs propriétés de la ressource, telles que l'emplacement, la quantité, le champ de commentaire, etc. scrap est DELETE? Dur à dire.

Une autre option consisterait à utiliser POST, où le corps inclut les instructions sur la manière d'opérer sur l'élément d'inventaire:

POST /inventory-transactions/{id}
{
    "action": "takeon",
    "newLocationId": 12345,
    ...
}

Cela vous donne beaucoup de traçabilité, car chaque opération peut maintenant être suivie en tant que ressource. L'inconvénient réside dans la complexité des points d'extrémité.

Vous pouvez également diviser certaines opérations "verbales" en ressources:

POST /returned-inventory
{
    "inventoryId": 12345,
    "documentId": 67890,
    "comment": "Busted up",
    ...
}

Cela vous permet de regarder facilement les articles d'inventaire en fonction de leur statut, ce qui peut ou non être utile. Vous pouvez, par exemple, appeler GET /returned-inventory?documentId=67890 pour récupérer tous les articles retournés du même document.

J'espère qu'il y a de quoi réfléchir. Il ne sera vraiment pas possible pour quiconque de vous dire la "bonne" chose à faire sans connaître vos exigences commerciales plus en détail.


30
2017-08-13 14:03



"Restful Objects", qui définit une API RESTful, indique que les actions sont valides.

Les actions disponibles peuvent être découvertes, activées / désactivées et peuvent donner une rétroaction «motivée».

Les actions sont 'invoquées' en utilisant GET (query), PUT (idempotent) ou POST (non idempotent)

Spécification d'objet reposant (page C-125)


8
2017-12-24 01:08