Comprendre le reste: les verbes, les codes d'erreur et l'authentification

je suis à la recherche d'un moyen d'envelopper APIs autour des fonctions par défaut dans Mes applications web PHP, bases de données et CMSs.

j'ai regardé autour et j'ai trouvé plusieurs cadres" squelettiques". En plus des réponses dans ma question, il y a tonique , un cadre de repos que j'aime parce qu'il est très léger.

J'aime le repos le meilleur pour sa simplicité, et je voudrais créer une architecture API basée sur elle. Je suis en train pour me faire à l'idée des principes de base et ne l'ont pas encore pleinement compris. Par conséquent, un certain nombre de questions.

1. Suis-je le comprendre, à droite?

Dire que j'ai une ressource "utilisateurs". Je pourrais mettre en place un certain nombre D'URIs comme cela:

/api/users     when called with GET, lists users
/api/users     when called with POST, creates user record
/api/users/1   when called with GET, shows user record
               when called with PUT, updates user record
               when called with DELETE, deletes user record

est-ce une représentation correcte d'une bonne architecture?

2. J'ai besoin de plus de verbes

créer, mettre à jour et Supprimer peut être suffisant en théorie, mais dans la pratique, j'aurai besoin de beaucoup plus de verbes. Je réalise que ce sont des choses que pourrait être intégré dans une requête de mise à jour, mais ce sont des actions spécifiques qui peuvent avoir des codes de retour spécifiques et je ne voudrais pas les jeter tous dans une action.

Certains qui viennent à l'esprit de l'utilisateur exemple:

activate_login
deactivate_login
change_password
add_credit

comment pourrais-je exprimer des actions telles que ceux dans une architecture D'URL Reposful?

mon instinct serait de faire un appel GET à une URL comme

/api/users/1/activate_login 

et attendez un code d'état de retour.

qui dévie de L'idée D'utiliser des verbes HTTP. Qu'en pensez-vous?

3. Comment retourner les messages d'erreur et les codes

une grande partie de la beauté de REST provient de son utilisation des méthodes HTTP standard. Sur un erreur, j'émets un en-tête avec un 3xx,4xx ou 5xx code d'état d'erreur. Pour une description détaillée de l'erreur, je peux utiliser le corps (non?). So far So good. Mais quelle serait la façon de transmettre un "code d'erreur propriétaire qui est plus détaillé dans la description de ce qui a mal tourné (par exemple" n'a pas réussi à se connecter à la base de données", ou"connexion à la base de données erronée")? Si je le mets dans le corps avec le message, je dois l'analyser après. Est-il un en-tête standard pour ce genre de chose?

4. Comment faire authentification

  • à quoi ressemblerait une authentification basée sur une clé API selon les principes REST?
  • y a-t-il des points forts contre l'utilisation de sessions lors de l'authentification D'un client REST, à part que c'est une violation flagrante du principe REST? :) (Je ne plaisante qu'à moitié ici, l'authentification basée sur les sessions fonctionnerait bien avec mon infrastructure existante.)
569
demandé sur SandroMarques 2010-01-04 22:55:36
la source

10 ответов

j'ai remarqué cette question quelques jours plus tard, mais je pense que je peux ajouter un peu de perspicacité. J'espère que cela peut être utile à l'égard de votre Réparateur entreprise.


Point 1: Ai-je bien compris?

vous avez bien compris. C'est une représentation correcte d'une architecture reposante. Vous pouvez trouver la matrice suivante de Wikipedia très utile pour définir vos noms et verbes:


lorsqu'il s'agit d'une Collection URI like: http://example.com/resources/

  • obtenez : liste des membres de la collection, complète avec leur URIs membre pour la navigation. Par exemple, énumérez toutes les voitures à vendre.

  • METTRE : Sens défini comme "remplacer la collection entière par une autre collection".

  • POST : créer une nouvelle entrée dans la collection où L'ID est attribué automatiquement par la collection. L'ID créé est généralement inclus dans les données retournées par cette opération.

  • supprimer : ce qui signifie"supprimer toute la collection".


lorsqu'il s'agit d'un membre URI like: http://example.com/resources/7HOU57Y

  • obtenez : récupérez une représentation du membre adressé de la collection exprimée dans un type MIME approprié.

  • PUT : mettre à jour le membre adressé de la collection ou créer avec l'ID spécifié.

  • POST : traite le membre visé comme une collection à part entière et en crée un nouveau subordonné.

  • supprimer : supprimer le membre destinataire de la collection.


Point 2: j'ai besoin de plus de verbes

En général, quand vous pensez que vous avez besoin de plus de verbes, il peut signifier que vos ressources doivent être ré-identifiés. Rappelez-vous qu'au repos vous agissez toujours sur une ressource, ou sur une collection de ressources. Ce que vous choisissez comme ressource est très important pour la définition de votre API.

Activer/Désactiver Login : si vous créez une nouvelle session, alors vous pouvez considérer" la session " comme la ressource. Pour créer une nouvelle session, utilisez POST à http://example.com/sessions/ avec les lettres de créance dans le corps. Pour l'expirer, utilisez PUT ou un DELETE (peut-être selon si vous avez l'intention de conserver un historique de session) à http://example.com/sessions/SESSION_ID .

changer le mot de passe: cette fois, la ressource est"l'utilisateur". Vous auriez besoin D'un PUT à http://example.com/users/USER_ID avec les anciens et les nouveaux mots de passe dans le corps. Vous agissez sur la ressource" l'utilisateur", et un mot de passe de changement est simplement une demande de mise à jour. C'est assez similaire à la mise à jour déclaration dans une base de données relationnelle.

mon instinct serait de faire un appel GET à une URL comme /api/users/1/activate_login

ceci va à l'encontre d'un principe de repos très fondamental: l'usage correct des verbes HTTP. Toute requête GET ne doit jamais laisser d'effet secondaire.

par exemple, une requête GET ne devrait jamais créer une session dans la base de données, renvoyer un cookie avec un nouvel identifiant de Session, ou laisser un résidu sur le serveur. Le verbe GET est comme la déclaration SELECT dans un moteur de base de données. Rappelez-vous que la réponse à toute requête avec le verbe GET doit pouvoir être mise en cache lorsqu'elle est demandée avec les mêmes paramètres, tout comme lorsque vous demandez une page Web statique.


Point 3: Comment retourner les messages d'erreur et les codes

considère les codes de statut HTTP 4xx ou 5xx comme des catégories d'erreurs. Vous pouvez élaborer l'erreur dans le corps.

N'a pas pu se connecter à la base de données: / connexion incorrecte de la base de données : en général, vous devez utiliser une erreur 500 pour ces types d'erreurs. C'est un serveur-côté d'erreur. Le client n'a rien fait de mal. 500 erreurs sont normalement considérées comme "réutilisables". c'est-à-dire que le client peut réessayer la même requête exacte, et s'attendre à ce qu'elle réussisse une fois les problèmes du serveur résolus. Spécifiez les détails dans le corps, de sorte que le client sera capable de nous fournir un contexte humain.

l'autre catégorie d'erreurs serait la famille 4xx, qui indique en général que le client a fait quelque chose de mal. En particulier, cette catégorie d'erreurs normalement indiquer au client qu'il n'est pas nécessaire de recommencer la demande comme il est, car il continuera à ne pas en permanence. c'est-à-dire que le client doit changer quelque chose avant de revenir sur cette requête. Par exemple, "Resource not found" (HTTP 404) ou " Malformed Request" (HTTP 400) les erreurs entreraient dans cette catégorie.


Point 4: Comment procéder à l'authentification

comme indiqué au point 1, au lieu d'authentifier un utilisateur, vous pouvez penser à créer une session. Vous recevrez un nouveau "ID de Session", ainsi que le code de statut HTTP approprié (200: accès accordé ou 403: Accès refusé).

vous demanderez alors votre repos serveur: "Pouvez-vous me fournir une ressource pour cet ID de Session?".

il n'y a pas de mode d'authentification - le reste est apatride: vous créez une session, vous demandez au serveur de vous fournir des ressources en utilisant cet ID de Session comme paramètre, et lors de la déconnexion vous supprimez ou expirez la session.

593
répondu Daniel Vassallo 2016-08-14 04:56:26
la source

simplement dit, vous faites cela complètement à l'envers.

vous ne devriez pas vous approcher de cela à partir de quelles URL vous devriez utiliser. Les URLs viendront effectivement "gratuitement" une fois que vous avez décidé quelles ressources sont nécessaires pour votre système et comment vous allez représenter ces ressources, et les interactions entre les ressources et l'état de l'application.

pour citer Roy Fielding "151980920

une API REST devrait dépenser presque tout son effort descriptif pour définir type(s) de support utilisé (s) pour représenter ressources et application de pilotage l'état, ou dans la définition élargie concernant les noms et/ou une marge de profit permettant l'utilisation de l'hypertexte pour les types de supports standard. Tout l'effort dépensé décrire les méthodes à utiliser sur ce Les centres d'intérêt devraient être entièrement définis dans le cadre de la les règles de traitement pour un type de média (et, dans la plupart des cas, déjà définis par types de supports existants). [Échec ici implique que hors bande l'information est le moteur de l'interaction au lieu de l'hypertexte.]

les gens commencent toujours par L'URIs et pensent que c'est la solution, puis ils ont tendance à manquer un concept clé dans l'architecture de repos, notamment, comme cité ci-dessus, "L'échec ici implique que l'information hors bande est le moteur de l'interaction au lieu de l'hypertexte."

pour être honnête, beaucoup voient un tas D'URIs et certains obtiennent et met et poste et pense que le repos est facile. Le REPOS n'est pas facile. RPC sur HTTP est facile, déplacer des blobs de données d'un bloc à l'autre via des charges utiles HTTP est facile. Le repos, cependant, va au-delà de cela. Le reste est du protocole agnostique. HTTP est juste très populaire et apt pour les systèmes de repos.

REST vit dans les types de médias, leurs définitions, et comment l'application conduit les actions disponibles à ces ressources via hypertexte (liens, effectivement).

il y a différents points de vue sur les types de supports dans les systèmes de repos. Certains préfèrent des charges utiles spécifiques à l'application, tandis que d'autres aiment élever les types de médias existants dans des rôles qui sont appropriés pour l'application. Par exemple, d'une part, vous avez des schémas XML spécifiques conçus pour votre application par rapport à l'utilisation de quelque chose comme XHTML comme votre représentation, peut-être par le biais de microformats et d'autres mécanismes.

les deux approches ont leur place, je pense, le XHTML fonctionne très bien dans les scénarios qui chevauchent à la fois le web piloté par l'homme et le web piloté par la machine, alors que les premiers types de données, plus spécifiques, je me sens mieux faciliter les interactions machine à machine. Je trouve que l'élévation des formats de marchandises peut rendre la négociation de contenu potentiellement difficile. "application / xml+yourresource" est beaucoup plus spécifique en tant que type de média que "application/xhtml+xml", car ce dernier peut s'appliquer à de nombreuses charges utiles qui peuvent être ou ne pas être quelque chose qu'un client machine est réellement intéressé par, NI peut-il déterminer sans introspection.

cependant, XHTML fonctionne très bien (évidemment) dans le web humain où les navigateurs web et le rendu sont très importants.

votre demande vous guidera dans ce genre de décisions.

une partie du processus de conception d'un système de repos est de découvrir les ressources de première classe dans votre système, avec le dérivé, les ressources de soutien nécessaires pour soutenir les opérations sur les ressources primaires. Une fois que les ressources sont découvertes, la représentation de ces ressources, ainsi que les diagrammes d'état montrant le flux des ressources via l'hypertexte dans les représentations parce que le prochain défi.

rappeler que chaque représentation d'une ressource, dans un système hypertexte, combine à la fois la représentation réelle de la ressource avec les transitions d'État disponibles à la ressource. Considérez chaque ressource comme un noeud dans un graphe, les liens étant les lignes qui quittent ce noeud. à d'autres états. Ces liens informent les clients non seulement de ce qui peut être fait, mais aussi de ce qui est requis pour qu'ils puissent le faire (car un bon lien combine L'URI et le type de média requis).

par exemple, vous pouvez avoir:

<link href="http://example.com/users" rel="users" type="application/xml+usercollection"/>
<link href="http://example.com/users?search" rel="search" type="application/xml+usersearchcriteria"/>

votre documentation parlera du champ rel nommé" users", et du type de média"application/xml+youruser".

ces liens peuvent sembler redondants, ils parlent tous à la même URI, à peu près. Mais ils ne sont pas.

c'est parce que pour la relation" users", ce lien parle de la collection des utilisateurs, et vous pouvez utiliser l'interface uniforme pour travailler avec la collection (obtenir de récupérer tous les, supprimer pour supprimer tous les, etc.)

si vous postez à cette URL, vous aurez besoin de passer un document "application / xml+usercollection", qui ne contiendra probablement qu'une seule instance utilisateur dans le document de sorte que vous pouvez ajouter l'utilisateur, ou non, peut-être, pour ajouter plusieurs à la fois. Peut-être votre documentation suggérera que vous pouvez simplement passer un type d'utilisateur simple, au lieu de la collection.

vous pouvez voir ce que l'application exige pour effectuer une recherche, comme défini par le lien" recherche " et c'est mediatype. La documentation pour le type de média de recherche vous indiquera comment cela se comporte, et ce qu'il faut attendre comme résultats.

l'emporter ici, cependant, est les URIs eux - mêmes sont essentiellement insignifiant. L'application est en contrôle de L'URIs, pas les clients. Au-delà de quelques "points d'entrée", Vos clients doivent s'appuyer sur les URI fournis par l'application pour leur travail.

le client a besoin de savoir comment manipuler et interpréter les types de médias, mais il n'a pas vraiment besoin de se soucier de l'endroit où il va.

ces deux liens sont sémantiquement identiques aux yeux d'un client:

<link href="http://example.com/users?search" rel="search" type="application/xml+usersearchcriteria"/>
<link href="http://example.com/AW163FH87SGV" rel="search" type="application/xml+usersearchcriteria"/>

alors, concentrez-vous sur vos ressources. Focus sur leurs transitions d'état dans l'application et la meilleure façon d'y parvenir.

76
répondu Will Hartung 2014-03-18 05:48:54
la source

re 1 : Cela ressemble bien de loin. Rappelez-vous de retourner L'URI de l'utilisateur nouvellement créé dans un en-tête "Location:" dans le cadre de la réponse à POST, avec un code de statut "201 Created".

re 2 : L'Activation via GET est une mauvaise idée, et inclure le verbe dans L'URI est une odeur de design. Vous pourriez vouloir envisager de retourner un formulaire sur une GET. Dans une application Web, il s'agirait D'un formulaire HTML avec un bouton Soumettre; dans L'utilisation de L'API case, vous pourriez vouloir retourner une représentation qui contient un URI à mettre pour activer le compte. Bien sûr, vous pouvez inclure cette URI dans la réponse sur POST to /users, aussi. L'utilisation de PUT garantit que votre requête est idempotent, c'est-à-dire qu'elle peut être envoyée à nouveau en toute sécurité si le client n'est pas sûr de son succès. En général, pensez aux ressources que vous pouvez transformer vos verbes en (sorte de "nounification des verbes"). Demandez-vous avec quelle méthode votre action spécifique est la plus étroitement alignée. E. g. change_password -> MIS; désactiver -> probablement SUPPRIMER; add_credit -> éventuellement POST ou PUT. Dirigez le client vers les URI appropriés en les incluant dans vos représentations.

re 3. n'inventez pas de nouveaux codes de statut, sauf si vous croyez qu'ils sont si génériques qu'ils méritent d'être normalisés à l'échelle mondiale. Essayez d'utiliser le code de statut le plus approprié Disponible (lisez à propos de tous les codes dans la RFC 2616). Inclure des renseignements supplémentaires dans l'organisme d'intervention. Si vous êtes vraiment, vraiment sûr que vous voulez inventer un nouveau code de statut, pensez encore; si vous le croyez encore, assurez-vous de choisir au moins la bonne catégorie (1XX - > OK, 2xx - > informationnel, 3xx - > redirection; 4xx - > erreur du client, 5xx - > erreur du serveur). Ai-je mentionné que l'invention de nouveaux codes de statut est une mauvaise idée?

re 4. si possible, utilisez le cadre d'authentification intégré dans HTTP. Découvrez la façon dont Google procède à l'authentification dans GData. Dans général, ne mettez pas les clés API dans votre URIs. Essayez d'éviter les sessions pour améliorer l'évolutivité et la prise en charge de la mise en cache - si la réponse à une requête diffère en raison de quelque chose qui s'est produit auparavant, vous avez généralement lié vous-même à une instance de processus de serveur spécifique. Il est préférable de transformer l'état de la session en état client (par exemple, l'inclure dans les requêtes subséquentes) ou de le rendre explicite en le transformant en état ressource (serveur), c'est-à-dire en lui donnant son propre URI.

29
répondu Stefan Tilkov 2012-03-23 19:53:18
la source

1. vous avez la bonne idée sur la façon de concevoir vos ressources, IMHO. Je ne voudrais pas changer une chose.

2. plutôt que d'essayer D'étendre HTTP avec plus de verbes, considérez ce à quoi vos verbes proposés peuvent être réduits en termes de méthodes et de ressources HTTP de base. Par exemple, au lieu d'un verbe activate_login , vous pouvez configurer des ressources comme: /api/users/1/login/active qui est un simple booléen. Pour activer une connexion, juste PUT un document qui dit "vrai" ou 1 ou n'importe quoi. Pour désactiver, PUT un document qui y est vide ou qui dit 0 ou false.

de même, pour changer ou définir les mots de passe, il suffit de faire PUT s à /api/users/1/password .

chaque fois que vous avez besoin d'ajouter quelque chose (comme un crédit) pensez en termes de POST S. Par exemple, vous pouvez faire un POST à une ressource comme /api/users/1/credits avec un corps contenant le nombre de crédits à ajouter. Un PUT sur la même ressource pourrait être utilisé pour écraser la valeur plutôt que d'ajouter. Un POST avec un nombre négatif dans le corps soustrairait, et ainsi de suite.

3. je déconseille fortement d'étendre les codes D'état HTTP de base. Si vous n'en trouvez pas un qui correspond exactement à votre situation, choisissez celui qui est le plus proche et mettez les détails de l'erreur dans le corps de la réponse. Aussi, rappelez-vous que les en-têtes HTTP sont extensibles; votre application peut définissez tous les en-têtes personnalisés que vous aimez. Une application sur laquelle j'ai travaillé, par exemple, pourrait retourner un 404 Not Found dans plusieurs circonstances. Plutôt que de faire de l'analyse client le corps de réponse pour cette raison, nous avons simplement ajouté un nouvel en-tête, X-Status-Extended , qui contenait nos extensions de code de statut propriétaires. Donc vous pourriez voir une réponse comme:

HTTP/1.1 404 Not Found    
X-Status-Extended: 404.3 More Specific Error Here

ainsi, un client HTTP comme un navigateur Web saura toujours quoi faire avec le code 404 normal, et un client HTTP plus sophistiqué peut choisir de regarder l'en-tête X-Status-Extended pour des informations plus spécifiques.

4. pour l'authentification, je recommande D'utiliser L'authentification HTTP Si vous le pouvez. Mais IMHO il n'y a rien de mal à utiliser l'authentification basée sur les cookies si c'est plus facile pour vous.

21
répondu friedo 2010-01-05 00:28:32
la source

les bases du repos

REST ont une contrainte d'interface uniforme, qui stipule que le client REST doit compter sur des normes au lieu de détails spécifiques à l'application du service de repos réel, de sorte que le client REST ne se brisera pas par des changements mineurs, et il sera probablement réutilisable.

il y a donc un contrat entre le client REST et le service REST. Si vous utilisez HTTP comme protocole sous-jacent, alors les normes suivantes font partie du contrat:

  • HTTP 1.1
    • méthode définitions de
    • définitions de code de statut
    • en-têtes
    • accepter et en-têtes content-type
    • auth-têtes
  • IRI (utf8 URI )
  • corps (choisir une)
  • hyperliens
    • ce que doit contenir (en choisir un)
      • envoyer lien les en-têtes
      • envoi d'une réponse hypermédia, par exemple html, atom+xml, hal+json, ld+JSON&hydra, etc...
    • sémantique
      • utilisation de l'IANA lien de relations et probablement en lien personnalisé relations
      • l'utilisation d'une application spécifique RDF vocab

le repos a une contrainte d'apatridie, qui déclare que la communication entre le service de repos et le client doit être apatride. Cela signifie que le service REST ne peut pas maintenir les États clients, de sorte que vous ne pouvez pas avoir de stockage de session côté serveur. Vous doivent authentifier chaque demande. Par exemple, HTTP basic auth (qui fait partie du standard HTTP) est correct, car il envoie le nom d'utilisateur et le mot de passe avec chaque requête.

pour répondre à vos questions

  1. Oui, c'est possible.

    juste pour mentionner, les clients ne se soucient pas de la structure IRI, ils se soucient de la sémantique, parce qu'ils suivent des liens ayant des relations de lien ou des données liées (RDF) attribut.

    la seule chose importante au sujet de L'IRIs, c'est qu'une seule IRI doit identifier une seule ressource. Il est permis à une seule ressource, comme un utilisateur, d'avoir de nombreux IRIs différents.

    c'est assez simple pourquoi nous utilisons de beaux IRIs comme /users/123/password ; il est beaucoup plus facile d'écrire la logique de routage sur le serveur quand vous comprenez L'IRI simplement en le lisant.

  2. vous avez plus de verbes, comme PUT, PATCH, les OPTIONS, et même plus, mais vous n'avez pas besoin de plus... Au lieu d'ajouter de nouveaux verbes, vous devez apprendre à ajouter de nouvelles ressources.

    activate_login -> PUT /login/active true deactivate_login -> PUT /login/active false change_password -> PUT /user/xy/password "newpass" add_credit -> POST /credit/raise {details: {}}

    (La connexion n'a pas de sens de REPOS point de vue, en raison de la apatrides contrainte.)

  3. vos utilisateurs ne se soucient pas de savoir pourquoi le problème existe. Ils veulent savoir seulement s'il y a un succès ou une erreur, et probablement un message d'erreur qu'ils peut comprendre, par exemple: "Désolé, mais nous n'avons pas pu enregistrer votre message.", etc...

    les en-têtes HTTP status sont vos en-têtes standards. Tout le reste devrait être dans le corps je pense. Un en-tête unique n'est pas suffisant pour décrire par exemple des messages d'erreur multilingues détaillés.

  4. la contrainte apatride (ainsi que les contraintes de cache et de système en couches) assure que le service fonctionne correctement. Vous avez sûrement ne pas wan pas à maintenez des millions de sessions sur le serveur, quand vous pouvez faire la même chose sur les clients...

    le client tiers obtient un token d'accès si l'utilisateur lui accorde l'accès en utilisant le client principal. Après cela, le client tiers envoie le jeton d'accès avec chaque demande. Il y a des solutions plus compliquées, par exemple vous pouvez signer chaque demande, etc. Pour plus de détails, consultez le manuel D'Auth.

littérature connexe

12
répondu inf3rno 2014-09-18 02:49:28
la source

pour les exemples que vous avez donnés, j'utiliserai ce qui suit:

activate_login

POST /users/1/activation

désactiver_login

DELETE /users/1/activation

change_password

PUT /passwords (cela suppose que l'utilisateur est authentifié)

add_credit

POST /credits (cela suppose que l'utilisateur est authentifié)

pour les erreurs, vous retournerez l'erreur dans le corps dans le format dans lequel vous avez reçu la demande, donc si vous recevez:

DELETE /users/1.xml

vous renverriez la réponse en XML, la même chose serait vraie pour JSON etc...

Pour l'authentification, vous devez utiliser l'authentification http.

11
répondu jonnii 2010-01-05 00:35:42
la source
  1. utilisez post lorsque vous ne savez pas à quoi ressemblerait la nouvelle URI ressource (vous créez un nouvel utilisateur, l'application assignerait son id au nouvel utilisateur), mettez à jour ou créez des ressources que vous savez comment elles seront représentées (exemple: PUT /myfiles/thisismynewfile.txt)
  2. retourner la description d'erreur dans le corps du message
  3. vous pouvez utiliser l'authentification HTTP (si c'est suffisant) Les services Web doivent être stateles
6
répondu Arjan 2010-01-04 23:06:15
la source

je suggère (en premier lieu) que PUT ne soit utilisé que pour la mise à jour des entités existantes. POST doit être utilisé pour en créer de nouveaux. c'est à dire

/api/users     when called with PUT, creates user record

ne me semble pas juste. Le reste de votre première section (ré. verbe usage) semble logique, cependant.

5
répondu Brian Agnew 2010-01-04 23:03:06
la source

Verbose, mais copié de la spécification de la méthode HTTP 1.1 à http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html

9.3 GET

la méthode GET signifie rechercher toute information (sous la forme d'une entité) identifiée par L'URI-Request. Si L'URI-demande fait référence à un processus de production de données, ce sont les données produites qui doivent être retournées en tant qu'entité dans la réponse et non le texte source de la processus, à moins que ce texte ne soit le résultat du processus.

la sémantique de la méthode GET change en "conditional GET" si le message de requête inclut un champ d'en-tête If-Modified-Sinu, If-Unmodified-Sinu, If-Match, If-None-Match, ou If-Range. Une méthode de GET conditionnel demande que l'entité soit transférée uniquement dans les circonstances décrites par le(s) champ (s) d'en-tête conditionnel (s). La méthode conditionnelle GET a pour but de réduire l'utilisation inutile du réseau en permettant aux entités mises en cache d'être rafraîchies sans avoir besoin de demandes multiples ou de transférer des données déjà détenues par le client.

la sémantique de la méthode GET change en "partial GET" si le message de requête inclut un champ D'en-tête Range. Un GET partiel demande que seule une partie de l'entité soit transférée, tel que décrit à la section 14.35. La méthode D'obtention partielle vise à réduire l'utilisation inutile du réseau en permettant aux entités partiellement récupérées d'être complétées sans transférer les données déjà détenues par le client.

la réponse à une requête GET peut être mise en cache si et seulement si elle satisfait aux exigences de mise en cache HTTP décrites à la section 13.

voir la section 15.1.3 pour les considérations de sécurité lors de l'utilisation des formulaires.

9.5 POST

La méthode POST est utilisée pour demander au serveur d'origine d'accepter l'entité incluse dans la requête comme subordonné de l' ressource identifiée par L'URI de la demande dans la ligne de la demande. POST est conçu pour permettre une méthode uniforme pour couvrir les fonctions suivantes:

  - Annotation of existing resources;
  - Posting a message to a bulletin board, newsgroup, mailing list,
    or similar group of articles;
  - Providing a block of data, such as the result of submitting a
    form, to a data-handling process;
  - Extending a database through an append operation.

la fonction réelle exécutée par la méthode POST est déterminée par le serveur et dépend habituellement de l'URI de la requête. Posté entité est subordonné que l'URI de la même manière qu'un fichier est subordonné à un répertoire contenant, un article de presse est subordonné à un groupe de discussion à laquelle il est publié, ou un enregistrement est subordonné à une base de données.

L'action effectuée par la méthode POST peut ne pas aboutir à une ressource qui peut être identifiée par une URI. Dans ce cas, 200 (OK) ou 204 (pas de contenu) est l'état de réponse approprié, selon que la réponse inclut ou non une entité qui décrit le résultat.

si une ressource a été créée sur le serveur d'origine, la réponse doit être 201 (Created) et contenir une entité qui décrit état de la requête et renvoie à la nouvelle ressource, et à un en-tête de localisation (voir la section 14.30).

les réponses à cette méthode ne peuvent pas être mises en cache, sauf si la réponse inclut les champs D'en-tête Cache-Control ou Expires appropriés. Cependant, la réponse 303 (voir autre) peut être utilisée pour demander à l'agent utilisateur de récupérer une ressource cachable.

les demandes postales doivent respecter les exigences de transmission de messages énoncées à la section 8.2.

Voir la section 15.1.3 pour les considérations relatives à la sécurité.

9.6 PUT

la méthode PUT demande que l'entité contenue soit stockée dans l'URI-requête fourni. Si L'URI-requête fait référence à une ressource déjà existante, l'entité jointe doit être considérée comme une version modifiée de celle qui se trouve sur le serveur d'origine. Si L'URI-requête ne pointe pas vers une ressource existante, et que L'URI est susceptible d'être défini comme une nouvelle ressource par le demander de l'agent utilisateur, le serveur d'origine peut créer la ressource avec d'URI. Si une nouvelle ressource est créée, le serveur d'origine doit en informer l'agent utilisateur via la réponse 201 (Created). Si une ressource existante est modifiée, les codes de réponse 200 (OK) ou 204 (pas de contenu) doivent être envoyés pour indiquer que la demande a été remplie avec succès. Si la ressource ne peut pas être créée ou modifiée avec L'URI-demande, une réponse d'erreur appropriée doit être donnée qui reflète la nature de la problème. Le destinataire de l'entité ne doit pas ignorer les en-têtes de contenu* (p. ex. Content-Range) qu'il ne comprend pas ou ne met pas en œuvre et doit retourner une réponse 501 (non mise en œuvre) dans de tels cas.

si la requête passe par un cache et que L'URI de la requête identifie une ou plusieurs entités actuellement mises en cache, ces entrées doivent être considérées comme périmées. Les réponses à cette méthode ne peuvent pas être mises en cache.

la différence fondamentale entre le poteau et Les requêtes PUT sont reflétées dans le sens différent de la requête-URI. L'URI dans une requête POST identifie la ressource qui traitera l'entité incluse. Cette ressource pourrait être un processus d'acceptation des données, une passerelle vers un autre protocole ou une entité distincte qui accepte les annotations. En revanche, L'URI d'une requête PUT identifie l'entité contenue dans la requête -- l'agent utilisateur sait à quoi L'URI est destinée et le serveur ne doit pas tenter d'appliquer la requête à une autre ressource. Si le serveur souhaite que la requête soit appliquée à un URI différent,

il doit envoyer une réponse 301 (déplacée en permanence); l'agent utilisateur peut alors prendre sa propre décision quant à savoir s'il convient ou non de rediriger la requête.

une seule ressource peut être identifiée par de nombreux URI différents. Par exemple, un article peut avoir une URI pour identifier "la version actuelle" qui est séparée de L'URI identifiant chaque version particulière. Dans ce cas, un PUT une requête sur un URI général peut conduire à la définition de plusieurs autres URI par le serveur d'origine.

HTTP/1.1 ne définit pas comment une méthode affecte l'état d'un serveur d'origine.

Les demandes de communication

doivent respecter les exigences de transmission de messages énoncées à la section 8.2.

sauf indication contraire pour un en-tête d'entité particulier, les en-têtes d'entité dans la requête PUT doivent être appliqués à la ressource créée ou modifiée par le METTRE.

9.7 supprimer

la méthode de suppression demande que le serveur d'origine supprime la ressource identifiée par L'URI-Request. Cette méthode peut être annulée par une intervention humaine (ou par d'autres moyens) sur le serveur d'origine. Le client ne peut pas être garanti que l'opération a été effectuée, même si le code d'état retourné par le serveur d'origine indique que l'action a été complétée avec succès. Cependant, le serveur ne doit pas indiquer succès à moins que, au moment où la réponse est donnée, il a l'intention de supprimer la ressource ou de la déplacer à un endroit inaccessible.

une réponse réussie devrait être 200 (OK) si la réponse comprend une entité décrivant le statut, 202 (accepté) si la mesure n'a pas encore été adoptée, ou 204 (pas de contenu) si la mesure a été adoptée, mais la réponse ne comprend pas une entité.

si la requête passe par un cache et que l'URI de la requête identifie une ou plusieurs entités actuellement mises en cache, ces entrées doivent être considérées comme périmées. Les réponses à cette méthode ne peuvent pas être mises en cache.

5
répondu gahooa 2010-01-04 23:10:14
la source

à propos des codes REST return: il est erroné de mélanger les codes de protocole HTTP et les résultats REST.

cependant, j'ai vu beaucoup d'implémentations les mélangeant, et beaucoup de développeurs peuvent ne pas être d'accord avec moi.

Les codes de retour HTTP

sont liés au HTTP Request lui-même. Un appel REST est fait en utilisant une requête de protocole de transfert hypertexte et fonctionne à un niveau inférieur à la méthode REST invoquée elle-même. REST est un concept / une approche, et son extrant est un résultat business / logique , tandis que le code de résultat HTTP est un transport un.

par exemple, retourner "404 Not found" quand vous appelez / users/ est confus, car il peut signifier:

  • URI est mal (HTTP)
  • Aucun utilisateur n'est trouvé (reste)

"403 Interdit/accès refusé" peut signifier:

  • spécial l'autorisation nécessaire. Les navigateurs peuvent le gérer en demandant à l'utilisateur/mot de passe. (HTTP)
  • permissions d'accès erronées configurées sur le serveur. (HTTP)
  • Vous devez être authentifié (RESTE)

et la liste peut continuer avec '500 Server error" (une erreur lancée par HTTP Apache/Nginx ou une erreur liée à une contrainte commerciale dans REST) ou d'autres erreurs HTTP, etc...

D'après le code, il est difficile de comprendre ce qui était la raison de l'échec, un échec HTTP (transport) ou un échec REST (logique).

si la requête HTTP a été matériellement exécutée avec succès, elle doit toujours retourner le code 200, quel que soit l'enregistrement trouvé ou non. Parce que la ressource URI est trouvée et a été gérée par le serveur http. Oui, il peut retourner un jeu vide. Est-il possible de recevoir une page Web vide avec 200 comme résultat http, n'est-ce pas?

à la place de cela, vous pouvez retourner 200 Code HTTP et simplement un JSON avec un tableau/objet vide, ou utiliser un indicateur de résultat/succès bool pour informer sur l'état de l'opération exécutée.

en outre, certains fournisseurs internet peuvent intercepter vos demandes et vous renvoyer un code http 404. Cela ne signifie pas que vos données ne sont pas trouvées, mais c'est quelque chose qui ne va pas au niveau du transport.

À Partir De Wiki :

En Juillet En 2004, le fournisseur de télécommunications britannique BT Group a déployé le Cleanfeed système de blocage de contenu, qui renvoie une erreur 404 à toute demande de contenu identifié comme potentiellement illégal par Internet Watch Fondation. D'autres FAI renvoient une erreur HTTP 403 "interdite" dans la même circonstance. La pratique d'employer des erreurs 404 faux comme un moyen de une censure cachée a également été signalée en Thaïlande et en Tunisie. Dans Tunisie, où la censure était sévère avant la révolution de 2011, gens pris conscience de la nature des erreurs de faux 404 et créé un personnage imaginaire nommé "Ammar 404", qui représente "l'invisible censurer."

2
répondu Marcodor 2017-09-23 15:08:47
la source

Autres questions sur rest web-services