9. Method Definitions (Définitions des Méthodes)
L'ensemble des méthodes communes pour HTTP/1.1 est défini ci-dessous. Bien que cet ensemble puisse être étendu, on ne peut pas supposer que des méthodes supplémentaires partagent la même sémantique pour les clients et serveurs étendus séparément.
Le champ d'en-tête Host (section 14.23) doit (MUST) accompagner toutes les requêtes HTTP/1.1.
9.1 Safe and Idempotent Methods (Méthodes Sûres et Idempotentes)
9.1.1 Safe Methods (Méthodes Sûres)
Les implémenteurs doivent être conscients que le logiciel représente l'utilisateur dans ses interactions sur Internet, et doivent faire attention à sensibiliser l'utilisateur aux actions qu'il pourrait entreprendre qui pourraient avoir une signification inattendue pour lui-même ou pour les autres.
En particulier, la convention établie est que les méthodes GET et HEAD ne devraient pas (SHOULD NOT) avoir la signification de prendre une action autre que la récupération. Ces méthodes devraient être considérées comme "sûres" (safe). Cela permet aux agents utilisateurs de représenter d'autres méthodes, telles que POST, PUT et DELETE, d'une manière spéciale, afin que l'utilisateur soit conscient du fait qu'une action possiblement non sûre est demandée.
Naturellement, il est impossible de s'assurer que le serveur ne génère pas d'effets secondaires lors de l'exécution d'une requête GET; en fait, certaines ressources dynamiques considèrent cela comme une fonctionnalité. La distinction importante ici est que l'utilisateur n'a pas demandé les effets secondaires, donc ne peut en être tenu responsable.
9.1.2 Idempotent Methods (Méthodes Idempotentes)
Les méthodes peuvent également avoir la propriété d'"idempotence" (idempotence) en ce sens que (à part les problèmes d'erreur ou d'expiration) les effets secondaires de N > 0 requêtes identiques sont les mêmes que pour une seule requête. Les méthodes GET, HEAD, PUT et DELETE partagent cette propriété. De plus, les méthodes OPTIONS et TRACE ne devraient pas (SHOULD NOT) avoir d'effets secondaires, et sont donc intrinsèquement idempotentes.
Cependant, il est possible qu'une séquence de plusieurs requêtes soit non idempotente, même si toutes les méthodes exécutées dans cette séquence sont idempotentes. (Par exemple, si le résultat ou l'état de toute ressource dépend de plusieurs requêtes dans la séquence.) Les requêtes POST ne sont pas idempotentes.
9.2 OPTIONS
La méthode OPTIONS représente une requête d'informations sur les options de communication disponibles sur la chaîne requête-réponse. Cette méthode permet au client de déterminer les options et/ou exigences associées à une ressource, ou les capacités d'un serveur, sans impliquer une action sur la ressource ou initier une récupération de ressource.
Les réponses à cette méthode ne sont pas cachables.
Si la requête OPTIONS inclut un corps d'entité (indiqué par la présence de Content-Length ou Transfer-Encoding), alors le type de média doit (MUST) être indiqué par un champ Content-Type. Bien que cette spécification ne définisse aucune utilisation pour un tel corps, les extensions HTTP futures pourraient utiliser le corps OPTIONS pour fournir des informations de requête plus détaillées au serveur. Un serveur qui ne prend pas en charge de telles extensions peut (MAY) rejeter le corps de la requête.
Si le Request-URI est un astérisque (""), la requête OPTIONS s'applique généralement au serveur plutôt qu'à une ressource spécifique. Étant donné que les options de communication d'un serveur dépendent généralement de la ressource, la requête "" est seulement utile comme méthode de type "ping" ou "no-op"; elle ne fait rien au-delà de permettre au client de tester les capacités du serveur. Par exemple, cela peut être utilisé pour tester la conformité HTTP/1.1 d'un proxy (ou son absence).
Si le Request-URI n'est pas un astérisque, la requête OPTIONS s'applique uniquement aux options disponibles lors de la communication avec cette ressource.
Une réponse 200 devrait (SHOULD) inclure tous les champs d'en-tête indiquant des fonctionnalités optionnelles s'ils s'appliquent à cette ressource (par exemple, Allow), incluant éventuellement des extensions non définies par cette spécification. Le corps de la réponse, s'il est inclus, devrait (SHOULD) également inclure des informations sur les options de communication. Cette spécification ne définit pas le format de ce corps, mais pourrait être défini dans les extensions futures 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 (MUST) inclure un champ Content-Length avec une valeur de champ de "0".
Le champ d'en-tête Max-Forwards peut (MAY) être utilisé pour cibler une requête vers un proxy spécifique dans la chaîne de requête. Lorsqu'un proxy reçoit une requête OPTIONS qui permet de transférer la requête, le proxy doit (MUST) vérifier le champ Max-Forwards. Si la valeur du champ Max-Forwards est zéro ("0"), le proxy ne doit pas (MUST NOT) transférer le message; au lieu de cela, le proxy devrait (SHOULD) répondre avec ses propres options de communication. Si la valeur du champ Max-Forwards est un entier supérieur à zéro, le proxy doit (MUST) décrémenter la valeur du champ et transférer la requête au serveur de saut suivant. Si aucun champ Max-Forwards n'est présent dans la requête OPTIONS, le proxy de transfert ne doit pas (MUST NOT) ajouter un champ Max-Forwards.
9.3 GET
La méthode GET signifie récupérer toutes les informations (sous forme d'entité) identifiées par le Request-URI. Si le Request-URI fait référence à un processus de production de données, ce sont les données produites qui devraient être renvoyées comme entité dans la réponse et non le texte source du processus, à moins que ce texte ne soit le résultat du processus.
Si le message de requête inclut un champ d'en-tête If-Modified-Since, If-Unmodified-Since, If-Match, If-None-Match ou If-Range, la sémantique de GET est modifiée en "GET conditionnel" (conditional GET). Une méthode GET conditionnelle demande que l'entité ne soit transférée que dans les circonstances décrites par le(s) champ(s) d'en-tête conditionnel. La méthode GET conditionnelle a pour but de réduire l'utilisation inutile du réseau en permettant de rafraîchir les entités en cache sans nécessiter plusieurs requêtes ou transférer des données déjà détenues par le client.
Si le message de requête inclut un champ d'en-tête Range, la sémantique de GET est modifiée en "GET partiel" (partial GET). Un GET partiel demande le transfert d'une partie seulement de l'entité, comme décrit dans la section 14.35. La méthode GET partielle a pour but de réduire l'utilisation inutile du réseau en permettant de compléter des entités partiellement récupérées sans transférer des données déjà détenues par le client.
La réponse à une requête GET est cachable si et seulement si elle satisfait aux exigences de mise en cache HTTP décrites dans la section 13.
Voir la section 15.1.3 pour les considérations de sécurité concernant les méthodes GET et HEAD.
9.4 HEAD
La méthode HEAD est identique à GET sauf que le serveur ne doit pas (MUST NOT) retourner un corps de message dans la réponse. Les méta-informations contenues dans les en-têtes HTTP en réponse à une requête HEAD devraient (SHOULD) être identiques aux informations envoyées en réponse à une requête GET. Cette méthode peut être utilisée pour obtenir des méta-informations sur l'entité impliquée par la requête sans transférer le corps de l'entité lui-même. Cette méthode est souvent utilisée pour tester la validité, l'accessibilité et la modification récente des liens hypertextes.
La réponse à une requête HEAD peut (MAY) être cachable dans le sens où les informations contenues dans la réponse peuvent être utilisées pour mettre à jour une entité précédemment mise en cache depuis cette ressource. Si les nouvelles valeurs de champ indiquent que l'entité mise en cache diffère de l'entité actuelle (comme l'indiquent les changements de Content-Length, Content-MD5, ETag ou Last-Modified), alors le cache doit (MUST) traiter l'entrée de cache comme périmée.
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 nouveau subordonné de la ressource identifiée par le Request-URI. POST est conçu pour permettre une méthode uniforme couvrant les fonctions suivantes:
- Annotation de ressources existantes;
- Publication d'un message sur un tableau d'affichage, un groupe de discussion, une liste de diffusion ou un groupe d'articles similaire;
- Fourniture d'un bloc de données (par exemple, soumission d'un formulaire) à un processus de traitement de données;
- Extension d'une base de données par une opération d'ajout.
La fonction réelle effectuée par la méthode POST est déterminée par le serveur et dépend généralement du Request-URI. L'entité postée est subordonnée à cet URI de la même manière qu'un fichier est subordonné au répertoire qui le contient, un article de presse est subordonné au groupe de discussion auquel il est posté, 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 un URI. Dans ce cas, 200 (OK) ou 204 (No Content) est le statut de réponse approprié, selon que la réponse inclut ou non une entité décrivant le résultat.
Si une ressource a été créée sur le serveur d'origine, la réponse devrait (SHOULD) être 201 (Created) et contenir une entité décrivant le statut de la requête et faisant référence à la nouvelle ressource, ainsi qu'un en-tête Location (voir section 14.30).
Les réponses à cette méthode ne sont pas cachables, sauf si la réponse inclut des champs d'en-tête Cache-Control ou Expires appropriés. Cependant, la réponse 303 (See Other) peut être utilisée pour diriger l'agent utilisateur vers la récupération d'une ressource cachable.
Les requêtes POST doivent (MUST) obéir aux exigences de transmission de messages décrites dans la section 8.2.
Voir la section 13.4 pour les considérations de mise en cache de la méthode POST.
9.6 PUT
La méthode PUT demande que l'entité incluse soit stockée sous le Request-URI fourni. Si le Request-URI fait référence à une ressource déjà existante, l'entité incluse devrait être considérée comme une version modifiée de celle résidant sur le serveur d'origine. Si le Request-URI ne pointe pas vers une ressource existante, et que cet URI est capable d'être défini comme nouvelle ressource par l'agent utilisateur demandeur, le serveur d'origine peut (can) créer la ressource avec cet URI. Si une nouvelle ressource est créée, le serveur d'origine doit (MUST) informer l'agent utilisateur via la réponse 201 (Created). Si une ressource existante est modifiée, soit les codes de réponse 200 (OK) soit 204 (No Content) devraient (SHOULD) être envoyés pour indiquer la réussite de la requête. Si la ressource ne peut pas être créée ou modifiée avec le Request-URI, une réponse d'erreur appropriée reflétant la nature du problème devrait (SHOULD) être donnée. Le destinataire de l'entité ne doit pas (MUST NOT) ignorer tout en-tête Content-* (par exemple Content-Range) qu'il ne comprend pas ou n'implémente pas, et doit (MUST) retourner une réponse 501 (Not Implemented) dans de tels cas.
Si la requête passe par un cache et que le Request-URI identifie une ou plusieurs entités actuellement mises en cache, ces entrées devraient (SHOULD) être traitées comme périmées. Les réponses à cette méthode ne sont pas cachables.
La différence fondamentale entre les requêtes PUT et POST se reflète dans la signification différente du Request-URI. L'URI dans une requête POST identifie la ressource qui traitera l'entité incluse. Cette ressource peut être un processus d'acceptation de données, une passerelle vers un autre protocole, ou une entité séparée qui accepte les annotations. En revanche, l'URI dans une requête PUT identifie l'entité incluse avec la requête - l'agent utilisateur sait quel URI est prévu et le serveur ne doit pas (MUST NOT) tenter d'appliquer la requête à une autre ressource. Si le serveur désire que la requête soit appliquée à un URI différent, il doit (MUST) envoyer une réponse 301 (Moved Permanently); l'agent utilisateur peut (MAY) alors décider par lui-même de rediriger ou non la requête.
Une seule ressource peut être identifiée par de nombreux URI différents. Par exemple, un article peut avoir un URI pour identifier la "version actuelle" qui est distinct des URI utilisés pour identifier chaque version particulière. Dans ce cas, une requête PUT sur l'URI générique pourrait résulter en ce que d'autres URI soient définis par le serveur d'origine.
HTTP/1.1 ne définit pas comment la méthode PUT affecte l'état du serveur d'origine.
Les requêtes PUT doivent (MUST) obéir aux exigences de transmission de messages décrites dans la section 8.2.
Sauf indication contraire spécifique, les effets secondaires de la méthode PUT devraient (SHOULD) être les mêmes que ceux d'envoyer une requête GET avec le même Request-URI.
9.7 DELETE
La méthode DELETE demande au serveur d'origine de supprimer la ressource identifiée par le Request-URI. Cette méthode peut (MAY) être outrepassée par une intervention humaine (ou 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 devrait pas (SHOULD NOT) indiquer le succès à moins qu'au moment où la réponse est donnée, il n'ait l'intention de supprimer la ressource ou de la déplacer vers un emplacement inaccessible.
Une réponse réussie devrait (SHOULD) être 200 (OK) si l'action a probablement réussi, 202 (Accepted) si l'action n'a pas encore été effectuée, ou 204 (No Content) si l'action a été effectuée mais la réponse n'inclut pas d'entité, même s'il est impossible de savoir si l'opération a été effectuée avec succès.
Si la requête passe par un cache et que le Request-URI identifie une ou plusieurs entités actuellement mises en cache, ces entrées devraient (SHOULD) être traitées comme périmées. Les réponses à cette méthode ne sont pas cachables.
9.8 TRACE
La méthode TRACE est utilisée pour invoquer une boucle de retour au niveau de la couche application distante du message de requête le long du chemin vers la ressource cible. Le destinataire final de la requête devrait (SHOULD) refléter le message reçu au client comme corps d'entité d'une réponse 200 (OK). Le destinataire final est soit le serveur d'origine, soit le premier proxy ou passerelle à recevoir une requête avec une valeur Max-Forwards de zéro (0) (voir section 14.31). Une requête TRACE ne doit pas (MUST NOT) inclure d'entité.
TRACE permet au client de voir ce qui est reçu à l'autre bout de la chaîne de requête et d'utiliser ces données pour des tests ou des informations de diagnostic. La valeur du champ d'en-tête Via (section 14.45) est d'un intérêt particulier car elle agit comme une trace de la chaîne de requête. L'utilisation de l'en-tête Max-Forwards permet au client de limiter la longueur de la chaîne de requête, ce qui est utile pour tester une chaîne de proxies transmettant des messages en boucle infinie.
Si la requête est valide, la réponse devrait (SHOULD) contenir le message de requête entier dans le corps d'entité, avec un Content-Type de "message/http". Les réponses à cette méthode ne doivent pas (MUST NOT) être mises en cache.
9.9 CONNECT
Cette spécification réserve le nom de méthode CONNECT pour une utilisation avec un proxy capable de basculer dynamiquement vers un tunnel (par exemple, tunnel SSL [44]).