Méthodes API RESTful; TÊTE ET OPTIONS


93

J'écris un module API RESTful pour une application en PHP, et je suis un peu mélangé les verbes HEADet OPTIONS.

  • OPTIONS  Utilisé pour récupérer les verbes HTTP disponibles pour une ressource donnée?
  • HEAD Utilisé pour déterminer si une ressource donnée est disponible?

Si quelqu'un pouvait clarifier * ces verbes, ce serait très apprécié.

* La clarification concernait les architectures d'API RESTful redéfinissant les verbes HTTP. Depuis, je me suis rendu compte que les deux HEADet neOPTIONS devraient pas être réutilisés, et se comportent plutôt de manière prévisible comme toute application HTTP le devrait. Oh, comment nous grandissons en 2 ans.


probablement parce que les spécifications HTTP sont facilement disponibles sur le Web.
Gordon

@Gordon - Assez juste, et bien que je comprenne que les services API RESTful sont destinés à tirer parti des spécifications HTTP existantes, je suppose que j'ai supposé un écart partiel pour les détails de mise en œuvre. Ma faute.
Dan Lugg

15
Les spécifications de presque tout sont facilement disponibles sur le Web. Les questions sur le SO sont pour clarification au-delà de la documentation. Cela correspond à cela.
Andrew Ensley

Réponses:


60

Selon: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html

9.2 OPTIONS

La méthode OPTIONS représente une demande d'informations sur les options de communication disponibles sur la chaîne de demande / réponse identifiée par Request-URI. Cette méthode permet au client de déterminer les options et / ou les exigences associées à une ressource, ou les capacités d'un serveur, sans impliquer une action de ressource ou lancer une extraction de ressource.

Les réponses à cette méthode ne peuvent pas être mises en cache.

Si la demande OPTIONS comprend un corps d'entité (comme indiqué par la présence de Content-Length ou de Transfer-Encoding), alors le type de support DOIT être indiqué par un champ Content-Type. Bien que cette spécification ne définisse aucune utilisation pour un tel corps, les futures extensions de HTTP pourraient utiliser le corps OPTIONS pour effectuer des requêtes plus détaillées sur le serveur. Un serveur qui ne prend pas en charge une telle extension PEUT rejeter le corps de la demande.

Si Request-URI est un astérisque ("*"), la demande OPTIONS est destinée à s'appliquer au serveur en général plutôt qu'à une ressource spécifique. Puisque les options de communication d'un serveur dépendent généralement de la ressource, la requête "*" n'est utile que comme méthode de type "ping" ou "no-op"; il ne fait rien d'autre que de permettre au client de tester les capacités du serveur. Par exemple, cela peut être utilisé pour tester un proxy pour la conformité HTTP / 1.1 (ou son absence).

Si Request-URI n'est pas un astérisque, la demande OPTIONS s'applique uniquement aux options disponibles lors de la communication avec cette ressource.

Une réponse 200 DEVRAIT inclure tous les champs d'en-tête qui indiquent des fonctionnalités facultatives implémentées par le serveur et applicables à cette ressource (par exemple, Autoriser), y compris éventuellement des extensions non définies par cette spécification. Le corps de réponse, le cas échéant, DEVRAIT également inclure des informations sur les options de communication. Le format d'un tel corps n'est pas défini par cette spécification, mais pourrait être défini par les futures extensions de HTTP. La négociation de contenu PEUT être utilisée pour sélectionner le format de réponse approprié. Si aucun corps de réponse n'est inclus, la réponse DOIT inclure un champ Content-Length avec une valeur de champ "0".

Le champ d'en-tête de demande Max-Forwards PEUT être utilisé pour cibler un mandataire spécifique dans la chaîne de demande. Lorsqu'un mandataire reçoit une demande OPTIONS sur une URL absolue pour laquelle la transmission de demande est autorisée, le mandataire DOIT vérifier la présence d'un champ Max-Forwards. Si la valeur de champ Max-Forwards est zéro ("0"), le mandataire NE DOIT PAS transmettre le message; au lieu de cela, le mandataire DEVRAIT répondre avec ses propres options de communication. Si la valeur de champ Max-Forwards est un entier supérieur à zéro, le mandataire DOIT décrémenter la valeur de champ lorsqu'il transmet la demande. Si aucun champ Max-Forwards n'est présent dans la demande, alors la demande transmise NE DOIT PAS inclure un champ Max-Forwards.

9.4 TÊTE

La méthode HEAD est identique à GET sauf que le serveur NE DOIT PAS renvoyer un corps de message dans la réponse. Les méta-informations contenues dans les en-têtes HTTP en réponse à une demande HEAD DEVRAIENT être identiques aux informations envoyées en réponse à une demande GET. Cette méthode peut être utilisée pour obtenir des méta-informations sur l'entité impliquée par la demande sans transférer le corps d'entité lui-même. Cette méthode est souvent utilisée pour tester la validité, l'accessibilité et les modifications récentes des liens hypertextes.

La réponse à une demande HEAD PEUT être mise en cache dans le sens que les informations contenues dans la réponse PEUVENT être utilisées pour mettre à jour une entité précédemment mise en cache à partir de cette ressource. Si les nouvelles valeurs de champ indiquent que l'entité mise en cache diffère de l'entité actuelle (comme cela serait indiqué par un changement dans Content-Length, Content-MD5, ETag ou Last-Modified), alors l'antémémoire DOIT traiter l'entrée d'antémémoire comme périmée.


1
Merci @sdolgy pour le devis complet; cependant, dans la pratique, de nombreux modules API RESTful réussis ( devraient-ils ) adhérer à toutes ces normes HTTP, ou existe-t-il une réponse mince acceptable pour ces opérations? Pas par paresse, mais simplement par curiosité; Je vais probablement mettre en œuvre tout le nécessaire pour adhérer.
Dan Lugg

2
si vous créez le vôtre, ce que je suppose que vous êtes, vous devriez essayer de maintenir un certain alignement avec les normes documentées pour vous faciliter la vie ... et celle des personnes qui utilisent votre API ... ne suivez pas Microsoft. Les RFC sont une bonne chose à aligner
sdolgy

Merci @sdolgy. Après avoir informé le document lié, j'ai remarqué à la fin le CONNECTverbe. Serait-ce un mauvais choix d'utiliser cette méthode pour l'authentification RESTful?
Dan Lugg

Pas sûr que c'était le but recherché "Cette spécification réserve le nom de la méthode CONNECT pour une utilisation avec un proxy qui peut passer dynamiquement à un tunnel (par exemple SSL tunneling [44])." ... peut être utile pour poster une autre question sur un des sites stackexchange.com à ce sujet ...
sdolgy

2
@DanLugg Votre application n'utilise peut-être pas CONNECTun tunnel SSL, mais imaginez ce qui se passerait si un consommateur de votre application avait un proxy implémenté CONNECTde la manière spécifiée dans la RFC, les requêtes pourraient ne pas être transmises à votre application.
Steve Buzonas

82

OPTIONSLa méthode renvoie des informations sur l' API (méthodes / type de contenu)

HEADLa méthode renvoie des informations sur la ressource (version / longueur / type)

Réponse du serveur

OPTIONS

HTTP/1.1 200 OK
Allow: GET,HEAD,POST,OPTIONS,TRACE
Content-Type: text/html; charset=UTF-8
Date: Wed, 08 May 2013 10:24:43 GMT
Content-Length: 0

TÊTE

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Type: text/html; charset=UTF-8
Date: Wed, 08 May 2013 10:12:29 GMT
ETag: "780602-4f6-4db31b2978ec0"
Last-Modified: Thu, 25 Apr 2013 16:13:23 GMT
Content-Length: 1270
  • OPTIONS Identifier les méthodes HTTP prises en charge par une ressource, par exemple pouvons-nous la SUPPRIMER ou la mettre à jour via un PUT?
  • HEADVérifier si une ressource a changé. Ceci est utile lors de la gestion d'une version mise en cache d'une ressource
  • HEAD Récupérer des métadonnées sur la ressource, par exemple son type de support ou sa taille, avant de procéder à une récupération éventuellement coûteuse
  • HEAD, OPTIONSTester si une ressource existe et est accessible. Par exemple, valider les liens soumis par l'utilisateur dans une application

Voici un article agréable et concis sur la façon dont HEAD et OPTIONS s'intègrent dans l'architecture RESTful.


9
Bonne réponse, dommage qu'il paiera la pénalité de retard à la fête. La réponse acceptée par copier-coller ne commence même pas à aborder spécifiquement la place de ces verbes dans une architecture RESTful.
Todd Menier

1
Votre lien est mort. Voici son dernier instantané: web.archive.org/web/20160528151316/https
kolobok

29

OPTIONS vous indique des choses telles que "Quelles méthodes sont autorisées pour cette ressource".

HEAD obtient l'en-tête HTTP que vous obtiendriez si vous faites une requête GET, mais sans le corps. Cela permet au client de déterminer les informations de mise en cache, quel type de contenu serait renvoyé, quel code d'état serait renvoyé. La disponibilité n'en est qu'une petite partie.


Merci @Quentin; OPTIONSétait ce que je pensais, et une telle mise en œuvre sera facile avec mon approche actuelle. Selon le devis RFC de sdolgy, OPTIONSne définit aucune norme dans le format. Est-il supposé que le format de réponse est le même que les autres réponses? ( par exemple; JSON, XML, etc. )
Dan Lugg

@Tomcat Citant la RFC: "La négociation de contenu PEUT être utilisée pour sélectionner le format de réponse approprié." En d'autres termes: la réponse doit être ce que la demande a demandé dans l'en-tête.
Gordon
En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.