Comment créer des URL REST sans verbes?

J’ai du mal à déterminer comment concevoir des URL reposantes. Je suis tout à fait pour l’approche reposante consistant à utiliser des URL avec des noms et non les verbes ne comprennent pas comment faire cela.

Nous créons un service pour mettre en œuvre une calculasortingce financière. La calculasortingce prend un tas de parameters que nous téléchargerons via un fichier CSV. Les cas d’utilisation impliqueraient:

  1. Télécharger de nouveaux parameters
  2. Obtenez les derniers parameters
  3. Obtenir des parameters pour une date commerciale donnée
  4. Rendre un ensemble de parameters actif
  5. Valider un ensemble de parameters

Je suppose que l’approche reposante consisterait à avoir les URL de type suivantes:

/parameters /parameters/12-23-2009 

Vous pouvez réaliser les trois premiers cas d’utilisation avec:

  1. POST où vous incluez le fichier de parameters dans la demande de publication
  2. GET de la première URL
  3. GET de la deuxième URL

Mais comment fais-tu le 4ème et le 5ème cas d’utilisation sans verbe? N’auriez-vous pas besoin d’URL comme:

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

??

Peut-être quelque chose comme:

 PUT /parameters/activation HTTP/1.1 Content-Type: application/json; encoding=UTF-8 Content-Length: 18 { "active": true } 

Principes généraux pour une bonne conception d’URI:

  • N’utilisez pas les parameters de requête pour modifier l’état
  • N’utilisez pas de chemins en casse mixte si vous pouvez l’aider; minuscule est le meilleur
  • N’utilisez pas d’ extensions spécifiques à l’implémentation dans vos URI (.php, .py, .pl, etc.)
  • Ne tombez pas dans le RPC avec vos URI
  • Limitez votre espace URI autant que possible
  • Gardez les segments de chemin courts
  • Préférez soit /resource ou /resource/ ; créer des redirections 301 à partir de celle que vous n’utilisez pas
  • Utilisez les parameters d’interrogation pour la sous-sélection d’une ressource. pagination, requêtes de recherche
  • Ne déplacez pas les éléments de l’URI qui doivent être dans un en-tête HTTP ou un corps

(Remarque: je n’ai pas dit “conception d’URI RESTful”; les URI sont essentiellement opaques dans REST.)

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

  • Ne jamais utiliser GET pour modifier l’état; c’est un excellent moyen de faire perdre la journée à Googlebot
  • N’utilisez pas PUT sauf si vous mettez à jour une ressource entière
  • N’utilisez pas PUT sauf si vous pouvez aussi légitimement faire un GET sur le même URI
  • N’utilisez pas POST pour récupérer des informations de longue durée ou susceptibles d’être mises en cache
  • Ne pas effectuer une opération qui n’est pas idempotente avec PUT
  • Utilisez GET pour autant que possible
  • Utilisez POST de préférence à PUT en cas de doute
  • Utilisez POST chaque fois que vous devez faire quelque chose qui ressemble à RPC
  • Utilisez PUT pour les classes de ressources plus grandes ou hiérarchiques
  • Utilisez DELETE de préférence à POST pour supprimer des ressources
  • Utilisez GET pour des choses comme les calculs, à moins que votre saisie soit grande, auquel cas utilisez POST

Principes généraux de la conception de services Web avec HTTP:

  • Ne placez pas de métadonnées dans le corps d’une réponse qui doit figurer dans un en-tête
  • Ne mettez pas de métadonnées dans une ressource distincte, à moins de l’inclure, cela créerait une surcharge importante
  • Utilisez le code de statut approprié
    • 201 Created après la création d’une ressource; la ressource doit exister au moment où la réponse est envoyée
    • 202 Accepted après avoir effectué une opération avec succès ou créé une ressource de manière asynchrone
    • 400 Bad Request lorsque quelqu’un effectue une opération sur des données qui sont clairement fausses; pour votre application, cela pourrait être une erreur de validation; réserve généralement 500 pour les exceptions non capturées
    • 401 Unauthorized lorsque quelqu’un accède à votre API sans fournir un en-tête d’ Authorization nécessaire ou lorsque les informations d’identification figurant dans l’ Authorization sont pas valides. n’utilisez pas ce code de réponse si vous n’attendez pas d’informations d’identification via un en-tête d’ Authorization .
    • 403 Forbidden lorsque quelqu’un accède à votre API de manière malveillante ou non autorisée
    • 405 Method Not Allowed lorsque quelqu’un utilise POST alors qu’il aurait dû utiliser PUT, etc.
    • 413 Request Entity Too Large volumineuse lorsque quelqu’un tente de vous envoyer un fichier 413 Request Entity Too Large volumineux
    • 418 I'm a teapot en essayant de préparer du café avec une théière
  • Utilisez des en-têtes de mise en cache chaque fois que vous le pouvez
    • ETag têtes ETag sont bons lorsque vous pouvez facilement réduire une ressource à une valeur de hachage
    • Last-Modified devrait vous indiquer que le maintien d’un horodatage de la mise à jour des ressources est une bonne idée
    • Cache-Control et Expires doivent recevoir des valeurs sensibles
  • Faites tout ce que vous pouvez pour honorer les en-têtes de mise en cache dans une requête ( If-None-Modified , If-Modified-Since )
  • Utilisez les redirections quand elles ont du sens, mais elles devraient être rares pour un service Web

En ce qui concerne votre question spécifique, POST devrait être utilisé pour # 4 et # 5. Ces opérations relèvent de la directive “RPC-like” ci-dessus. Pour # 5, rappelez-vous que POST ne doit pas nécessairement utiliser Content-Type: application/x-www-form-urlencoded . Cela pourrait aussi bien être une charge utile JSON ou CSV.

Chaque fois que vous avez besoin d’un nouveau verbe, pensez à transformer ce verbe en un nom à la place. Par exemple, activez «activation» et validez en «validation».

Mais d’après ce que vous avez écrit, je dirais que votre application a beaucoup plus de problèmes.

Chaque fois qu’une ressource appelée «paramètre» est proposée, elle devrait envoyer des signaux d’alarme dans l’esprit de chaque membre de l’équipe de projet. “paramètre” peut littéralement s’appliquer à n’importe quelle ressource; ce n’est pas assez précis.

Que représente exactement un paramètre? Probablement un certain nombre de choses différentes, chacune devant avoir une ressource distincte qui lui est dédiée.

Une autre façon d’y parvenir – lorsque vous discutez de votre application avec les utilisateurs finaux (ceux qui connaissent probablement peu la programmation), quels sont les mots qu’ils utilisent eux-mêmes à plusieurs resockets?

Ce sont les mots que vous devriez concevoir votre application autour.

Si vous n’avez pas encore eu cette conversion avec des utilisateurs potentiels – arrêtez tout de suite et n’écrivez pas une autre ligne de code jusqu’à ce que vous l’ayez fait! Alors seulement, votre équipe aura une idée de ce qui doit être construit.

Je ne connais rien aux logiciels financiers, mais si je devais deviner, je dirais que certaines ressources pourraient porter des noms tels que “Rapport”, “Paiement”, “Transfert” et “Devise”.

Il existe un certain nombre de bons livres sur cette partie du processus de conception de logiciels. Je peux vous recommander deux modèles de conception et d’ parsing pilotés par le domaine .

La conception de vos URL n’a rien à voir avec le fait que votre application soit RESTful ou non. la phrase “RESTful URLS” est donc un non-sens.

Je pense que vous devriez faire plus de lecture sur ce qu’est REST. REST considère les URL comme opaques et, en tant que telles, ne sait pas ce qu’elles contiennent, qu’il s’agisse de verbes, de noms ou autre. Vous voudrez peut-être toujours concevoir vos URL, mais il s’agit de l’interface utilisateur, pas de REST.

Cela dit, passons à votre question: les deux derniers cas ne sont pas corrects et ne correspondent à aucun type de programme reposant. C’est ce que vous pourriez appeler RPC. Si vous êtes sérieux au sujet de REST, vous devrez repenser le fonctionnement de votre application à partir de zéro. Soit cela, soit abandonner REST et juste faire votre application en tant qu’application RPC.

Hmmmm peut-être pas.

L’idée ici est que vous devez tout traiter comme une ressource, donc une fois qu’un ensemble de parameters a une URL, vous pouvez vous y référer, il vous suffit d’append

obtenir des parameters / résultats de validation

poster [paramatersurl]

body: {commande: “activate”}

mais encore une fois, cette chose active est RPC, pas REST.

Les exigences d’activation et de validation sont des situations dans lesquelles vous tentez de modifier l’état d’une ressource. Ce n’est pas différent de rendre une commande “terminée” ou une autre demande “soumise”. Il existe de nombreuses façons de modéliser ces types de changement d’état, mais je pense que cela fonctionne souvent: créer des ressources de collecte pour les ressources du même état, puis déplacer la ressource entre les collections pour affecter l’état.

Par exemple, créer des ressources telles que

 /ActiveParameters /ValidatedParameters 

Si vous souhaitez activer un ensemble de parameters, ajoutez ce jeu à la collection ActiveParameters. Vous pouvez soit passer le jeu de parameters en tant que corps d’entité, soit passer une URL en tant que paramètre de requête, comme suit:

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

La même chose peut être faite avec les / ValidatedParameters. Si les parameters ne sont pas valides, le serveur peut renvoyer la requête “Bad Request” pour append les parameters à la collecte des parameters validés.

Je suggère la ressource et les méthodes Meta suivantes.

Rendre les parameters actifs et / ou les valider:

 > PUT /parameters//meta HTTP/1.1 > Host: example.com > Content-Type: application/json > Connection: close > > {'active': true, 'require-valid': true} > < HTTP/1.1 200 OK < Connection: close < 

Vérifiez si les parameters sont actifs et valides:

 > GET /parameters//meta HTTP/1.1 > Host: example.com > Connection: close > < HTTP/1.1 200 OK < Content-Type: application/json < Connection: close < < { < 'active': true, < 'require-valid': true, < 'valid': {'status': false, 'reason': '...'} < } < 

Dans un environnement REST, chaque URL est une ressource unique. Quelles sont vos ressources? Une calculasortingce financière n’a pas de ressources évidentes. Vous devez parsingr vos parameters et extraire les ressources. Par exemple, un calendrier d’amortissement pour un prêt peut être une ressource. L’URL du calendrier peut inclure date_début, terme (en mois ou années), période (lorsque l’intérêt est composé), taux d’intérêt et principe initial. Avec toutes ces valeurs, vous avez un calendrier de paiement spécifique:

 http://example.com/amort_cal/2009-10-20/30yrsfixed/monthly/5.00/200000 

Maintenant, je ne sais pas ce que vous calculez, mais votre concept de liste de parameters ne sonne pas RESTful. Comme quelqu’un d’autre l’a dit, vos exigences ci-dessus sonnent plus XMLRPC. Si vous essayez REST, vous avez besoin de noms. Les calculs ne sont pas des noms, ils sont des verbes qui agissent sur les noms. Vous devez le retourner pour extraire les noms de vos calculs.

Edit: En effet, l’URI aurait empêché GET requêtes GET de restr idempotentes.


Pour la validation cependant, l’utilisation de codes d’état HTTP pour notifier la validité d’une requête (pour créer un nouveau paramètre ou modifier un paramètre existant) correspondrait à un modèle Restful.

Rapportez avec un code d’état 400 Bad Request si les données soumises sont / ne sont pas valides et que la demande doit être modifiée avant d’être soumise à nouveau ( codes d’état HTTP / 1.1 ).

Cela dépend de la validation au moment de la soumission, plutôt que de la reporter comme dans votre cas d’utilisation. Les autres réponses ont des solutions adaptées à ce scénario.