web-dev-qa-db-fra.com

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

Je construis un système de gestion des stocks et je suis en train de concevoir (penser) à l'API et à ma mise en œuvre 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 recherche des commentaires d'experts en ce qui concerne l'utilisabilité et l'acceptabilité en ce qui concerne la conception d'URL et de ressources. Les pièges et les exemples du monde réel, toute opinion ou critique bienvenue.

Mes préoccupations sont que l'application entière pourrait être développée autour de cette grande ressource? Ma pile backend sera le framework C # et servicestack et pour le frontend j'utiliserai HTML et AngularJS. Non pas que cela fasse une différence.

Scénario 1. Le fonctionnement 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

puis pour changer les ressources.

Scénario 3. à mon avis, faux

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/{...}

Des commentaires bienvenus, ne cherchez pas de réponse mais plus de conseils sur les considérations de conception?

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

restarchitectureservicestack
36
Francois Taljaard

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.

Fondamental du schéma architectural REST est l'idée d'utiliser les verbes HTTP comme seul verbe, et de ne pas inclure les verbes dans vos URL. À votre place, j'envisagerais 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. Beaucoup de ces actions semblent être en réalité de simples PUT qui mettent à jour plusieurs propriétés de la ressource, telles que l'emplacement, la quantité, le champ de commentaire, etc. Et peut-être que scrap est SUPPRIMÉ? Dur à dire.

Une autre option serait d'utiliser POST, où le corps comprend les instructions sur la façon d'opérer sur l'article d'inventaire:

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

Cela vous donne beaucoup de traçabilité, car chaque opération peut désormais être suivie en tant que ressource. L'inconvénient est une grande complexité autour du point final.

Vous pouvez également décomposer certaines des opérations "verbe" en ressources:

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

Cela vous permet de consulter facilement les articles en stock en fonction de leur statut, ce qui peut être utile ou non. 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 matière à réflexion. Il ne sera vraiment pas possible pour quiconque de vous dire la "bonne" chose à faire sans connaître plus en détail les besoins de votre entreprise.

40
Eric Stein

"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 des commentaires sur la "raison désactivée".

Les actions sont "invoquées" à l'aide de GET (requête), PUT (idempotent) ou POST (non idempotent)

Spéc. Objet reposant (page C-125)

13
Patrick

Réponse courte :

Utilisez des actions à la fin de l'URL pour changer d'état.

Github fait ça pour lancer un Gist: PUT/gists /: Gist_id/star

Expliqué ici https://developer.github.com/v3/gists/#star-a-Gist

Réponse longue :

Votre objectif est de rendre vos applications sans effort pour utiliser une interface intuitive. Vos utilisateurs doivent utiliser votre application de la manière la plus simple possible. Vos utilisateurs ne devraient pas subir les limitations ou les directives strictes des technologies que vous utilisez.

Ainsi, les actions et opérations ne sont pas intrinsèquement des ressources, mais des actions sur les ressources. Ils ne répondront donc pas à une "ressource vers un mappage d'URI" comme REST is.

Mais vous pouvez utiliser le meilleur de REST, et toujours le meilleur des URI, en combinant les deux.

N'oubliez pas:

La technologie devrait fonctionner pour vous et non pour la technologie.

Si vous devenez un esclave de la technologie, vous finirez par créer des applications inutilisables ou en utilisant des technologies laides comme XML ou Java Interfaces Home et Remote, vous finirez donc par écrire 5 fichiers pour créer une application Hello World .

Méfiez-vous du "syndrome de l'objet brillant". Recherche le sur Google.

Non pas parce qu'une technologie est nouvelle ou est "la nouvelle façon de faire les choses", cela signifie que c'est une bonne technologie ou que vous devez vous laisser distraire et laisser de côté toutes les autres technologies pour succomber au REST.

Prenez ce dont vous avez besoin de la technologie, puis faites fonctionner la technologie pour vous.

L'utilisation de REST api ne signifie pas que vous devez ignorer les capacités des technologies URL et URI.

Références: https://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#restful

4
1P0