Comment créer des URL REST sans verbes?

Question

J'ai du mal à déterminer comment la conception reposant Url. Je suis tout à fait pour le repos de l'approche de l'utilisation d'Url avec des noms et non des verbes ne comprends pas comment faire cela.

Nous sommes la création d'un service pour mettre en œuvre une calculatrice financière. Le calculateur prend un tas de paramètres que nous allons le télécharger via un fichier CSV. Les cas d'utilisation impliquerait:

1. Télécharger de nouveaux paramètres
2. Obtenez les derniers paramètres
3. Obtenir les paramètres pour une entreprise date de
4. Faire un jeu de paramètres actif
5. Valider un ensemble de paramètres

J'ai rassembler le repos approche serait d'avoir ce type d'Url:

/parameters
/parameters/12-23-2009

Vous pouvait atteindre le premier des trois cas d'utilisation avec:

1. POST où vous incluez le fichier de paramètre dans la requête post
2. OBTENEZ de première URL
3. OBTENEZ de deuxième URL

Mais comment faites-vous les 4 et 5 cas d'utilisation sans verbe? N'auriez-vous pas besoin d'Url comme:

/parameters/ID/activate
/parameters/ID/validate

??

Answer 1

Principes généraux de bonne URI de conception:

• Ne pas utiliser les paramètres de requête pour modifier l'état
• Ne pas utiliser les majuscules et les chemins d'accès si vous pouvez vous le permettre; la minuscule est meilleur
• Ne pas utiliser la mise en œuvre des extensions spécifiques à votre Uri (.php, .py, .pl, etc.)
• Ne pas tomber dans la RPC avec votre Uri
• Ne limitez votre URI de l'espace autant que possible
• Faire garder les segments de tracé court
• Ne préfèrent /resource ou /resource/; créer des redirections 301 de l'un que vous ne l'utilisez pas
• Faire usage de paramètres de requête pour les sous-sélection d'une ressource; c'est à dire la pagination, les requêtes de recherche
• Faire bouger des choses de l'URI qui devrait être dans un en-tête HTTP ou un corps

(Note: je n'ai pas dit de "repos URI design"; Uri sont essentiellement opaque en RESTE.)

Principes généraux pour HTTP choix de la méthode:

• Ne jamais utiliser GET pour modifier l'état; c'est une excellente façon d'avoir le Googlebot ruiner votre journée
• Ne pas utiliser les METTRE, sauf si vous êtes à la mise à jour d'un ensemble de ressources
• Ne pas utiliser MIS à moins que vous pouvez aussi légitimement faire un GET sur la même URI
• Ne pas utiliser la POSTE pour récupérer des informations qui est de longue durée ou qui pourrait être raisonnable de cache
• Ne pas effectuer une opération qui n'est pas équipotent à METTRE
• N' utiliser pour OBTENIR autant que possible
• Faire usage de POSTE, de préférence à METTRE dans le doute
• N' utilisez POST à chaque fois que vous avez à faire quelque chose qui se sent RPC-comme
• N' utilisez PUT pour les classes de ressources qui sont plus ou hiérarchique
• N' utilisez SUPPRIMER, de préférence à la POSTE pour retirer des ressources
• N' utilisez GET pour des choses comme les calculs, sauf si votre entrée est grand, auquel cas l'utilisation de POST

Principes généraux du service web design avec HTTP:

• Ne pas mettre de métadonnées dans le corps d'une réponse qui devrait être dans un en-tête
• Ne pas mettre de métadonnées dans une autre ressource, à moins que notamment il serait de créer une surcharge importante
• N' utilisez le code d'état
  • 201 Created après la création d'une ressource, la ressource doit exister au moment de la réponse est envoyée
  • 202 Accepted après l'exécution d'une opération avec succès ou la création d'une ressource de manière asynchrone
  • 400 Bad Request lorsque quelqu'un effectue une opération sur des données manifestement faux; pour votre application, cela pourrait être une erreur de validation; en général, la réserve de 500 pour les exceptions non traitées
  • 401 Unauthorized lorsque quelqu'un accède à votre API, soit sans fournir un nécessaire Authorization - tête ou lorsque les informations d'identification au sein de l' Authorization ne sont pas valides; n'utilisez pas ce code de réponse si vous ne s'attendent pas les informations d'identification via un Authorization - tête.
  • 403 Forbidden lorsque quelqu'un accède à votre API dans une manière qui pourrait être malveillant ou s'ils ne sont pas autorisés
  • 405 Method Not Allowed quand quelqu'un utilise POST, quand ils auraient dû METTRE, etc
  • 413 Request Entity Too Large lorsque quelqu'un tente de vous envoyer inacceptable fichier
  • 418 I'm a teapot lors de la tentative de préparer le café avec un verre d'eau
• N' utiliser la mise en cache des en-têtes à chaque fois que vous pouvez
  • ETag - têtes sont bons quand vous pouvez facilement réduire à une ressource d'une valeur de hachage
  • Last-Modified devrait vous indiquer que le maintien autour d'un horodatage de lorsque les ressources sont mis à jour est une bonne idée
  • Cache-Control et Expires devrait être donnée sensible valeurs
• Faire tout ce que vous pouvez pour l'honneur de la mise en cache des en-têtes dans une demande (If-None-Modified, If-Modified-Since)
• Faire utiliser des redirections quand elles ont un sens, mais ce doit être rare pour un service web

Quant à votre question spécifique, le POST doit être utilisé pour le #4 et #5. Ces opérations relèvent de la "RPC" comme de la directive ci-dessus. Pour n ° 5, n'oubliez pas que le POST n'a pas nécessairement besoin d'utiliser Content-Type: application/x-www-form-urlencoded. Cela pourrait tout aussi bien être un JSON ou CSV charge utile.

Answer 2

Peut-être quelque chose comme:

 PUT /parameters/activation HTTP/1.1
Content-Type: application/json; encoding=UTF-8
Content-Length: 18

{ "active": true }
 

Answer 3

Chaque fois qu'il semble que vous ayez besoin d'un nouveau verbe, pensez à la possibilité de transformer cette verbe d'un nom à la place. Par exemple, s'adresser à "activer" dans "activation", et "valider" en "validation".

Mais seulement de ce que vous avez écrit, je dirais que votre demande a bien plus de problèmes.

Tout moment une ressource appelée "paramètre" est proposé, il doit envoyer le rouge des drapeaux de chaque membre d'équipe de projet de l'esprit. "paramètre" peut littéralement s'appliquent à toutes les ressources; il n'est pas assez précis.

Que fait exactement un 'paramètre' représentent-ils? Probablement un certain nombre de choses différentes, que chacun doit avoir une ressource dédiée.

Une autre façon d'obtenir de cela, lorsque vous discutez de votre application avec les utilisateurs finaux (ceux qui savez peu de choses sur la programmation) quels sont les mots qu'ils utilisent eux-mêmes à plusieurs reprises?

Ce sont les mots que vous devrait à la conception de votre application autour.

Si vous n'avez pas encore eu cette conversion avec les futurs utilisateurs de tout arrêter dès maintenant et de ne pas écrire une ligne de code jusqu'à ce que vous faites! Alors seulement, votre équipe avez une idée de ce qui doit être construit.

Je ne sais rien au sujet de logiciel financier, mais si je devais deviner, je dirais que certains de ces ressources pourrait passer par des noms tels que "Rapport", "Paiement", "Transfert", et la "Monnaie".

Il y a un certain nombre de bons livres sur cette partie du processus de création de logiciels. De deux, je peux vous recommander sont Domain Driven Design et les Modèles d'Analyse.

Answer 4

La conception de votre url n'a rien à voir avec le fait que votre application est Reposante ou pas. l'expression de "repos URL" est donc une absurdité.

Je pense que vous devriez faire un peu plus de lecture sur ce qui RESTE est en réalité. RESTE traite l'URL comme opaque, et en tant que tel ne sais pas ce que est en eux, si il y a des verbes ou des noms ou quoi que ce soit. Vous pouvez toujours concevoir votre URL, mais c'est à propos de l'INTERFACE utilisateur, pas de REPOS.

Cela dit, permet de se rendre à votre question: Les deux derniers cas ne sont pas Reposantes, et ne rentre pas dans n'importe quel type de régime reposant. Ceux-ci sont ce qu'on pourrait appeler de la RPC. Si vous êtes sérieux au sujet de REPOS, vous aurez à repenser la façon dont votre application fonctionne à partir de la base. Soit ça, ou abandonner le RESTE et il suffit de faire votre application comme une application RPC.

Hrmmm peut-être pas.

L'idée ici est que vous devez à tout traiter comme une ressource, pour une fois un jeu de paramètres a une URL que vous pouvez consulter à partir, vous venez d'ajouter

[parametersurl]/validationresults

post [paramatersurl]

corps: {commande:"activer"}

mais encore une fois, qui activent chose est RPC, pas de REPOS.

Answer 5

L'activer et valider les exigences sont les situations où vous êtes en essayant de changer l'état d'une ressource. Il n'est pas différent que de faire une commande "terminé", ou une autre demande de "soumis". Il existe de nombreuses façons de modéliser ces types de changement d'état, mais celui que je trouve que souvent, les œuvres, c'est pour créer une collection de ressources pour les ressources d'un même état et à déplacer la ressource entre les collections de nuire à l'état.

par exemple, la création de certaines ressources telles que,

/ActiveParameters
/ValidatedParameters

Si vous voulez faire un jeu de paramètres actif, puis ajouter ce jeu à la ActiveParameters collection. Vous pouvez soit passer le jeu de paramètres comme un corps d'entité, ou vous pouvez passer une url comme un paramètre de requête, comme suit:

POST /ActiveParameters?parameter=/Parameters/{Id}

La même chose peut être fait avec l' /ValidatedParameters. Si les Paramètres ne sont pas valides ensuite, le serveur peut renvoyer des "Bad Request" à la demande d'ajouter les paramètres de la collecte de validation des paramètres.