9. Method Definitions (Methodendefinitionen)
Die Menge der gängigen Methoden für HTTP/1.1 ist im Folgenden definiert. Obwohl diese Menge erweitert werden kann, kann nicht davon ausgegangen werden, dass zusätzliche Methoden für separat erweiterte Clients und Server dieselbe Semantik teilen.
Das Host-Anfrage-Header-Feld (Abschnitt 14.23) muss (MUST) alle HTTP/1.1-Anfragen begleiten.
9.1 Safe and Idempotent Methods (Sichere und Idempotente Methoden)
9.1.1 Safe Methods (Sichere Methoden)
Implementierer sollten sich bewusst sein, dass Software den Benutzer in seinen Interaktionen im Internet repräsentiert und vorsichtig sein sollten, den Benutzer auf jede Handlung aufmerksam zu machen, die er möglicherweise unternimmt, die für ihn selbst oder andere eine unerwartete Bedeutung haben könnte.
Insbesondere besteht die etablierte Konvention darin, dass die Methoden GET und HEAD keine (SHOULD NOT) andere Handlungsbedeutung als die Abrufung haben sollten. Diese Methoden sollten als "sicher" (safe) betrachtet werden. Dies ermöglicht es Benutzeragenten, andere Methoden wie POST, PUT und DELETE auf besondere Weise darzustellen, sodass der Benutzer sich bewusst ist, dass eine möglicherweise unsichere Aktion angefordert wird.
Natürlich ist es unmöglich sicherzustellen, dass der Server bei der Ausführung einer GET-Anfrage keine Nebenwirkungen erzeugt; tatsächlich betrachten einige dynamische Ressourcen dies als Feature. Der wichtige Unterschied hier besteht darin, dass der Benutzer die Nebenwirkungen nicht angefordert hat und daher nicht dafür verantwortlich gemacht werden kann.
9.1.2 Idempotent Methods (Idempotente Methoden)
Methoden können auch die Eigenschaft der "Idempotenz" (idempotence) haben, in dem Sinne, dass (abgesehen von Fehler- oder Ablaufproblemen) die Nebenwirkungen von N > 0 identischen Anfragen dieselben sind wie für eine einzelne Anfrage. Die Methoden GET, HEAD, PUT und DELETE teilen diese Eigenschaft. Darüber hinaus sollten die Methoden OPTIONS und TRACE keine (SHOULD NOT) Nebenwirkungen haben und sind daher von Natur aus idempotent.
Es ist jedoch möglich, dass eine Sequenz von mehreren Anfragen nicht idempotent ist, selbst wenn alle in dieser Sequenz ausgeführten Methoden idempotent sind. (Zum Beispiel, wenn das Ergebnis oder der Zustand einer beliebigen Ressource von mehreren Anfragen in der Sequenz abhängt.) POST-Anfragen sind nicht idempotent.
9.2 OPTIONS
Die OPTIONS-Methode repräsentiert eine Anfrage nach Informationen über die Kommunikationsoptionen, die auf der Anfrage-Antwort-Kette verfügbar sind. Diese Methode ermöglicht es dem Client, die mit einer Ressource verbundenen Optionen und/oder Anforderungen oder die Fähigkeiten eines Servers zu bestimmen, ohne eine Ressourcenaktion zu implizieren oder eine Ressourcenabrufung einzuleiten.
Antworten auf diese Methode sind nicht cachebar.
Wenn die OPTIONS-Anfrage einen Entitätskörper enthält (angezeigt durch das Vorhandensein von Content-Length oder Transfer-Encoding), muss (MUST) der Medientyp durch ein Content-Type-Feld angegeben werden. Obwohl diese Spezifikation keine Verwendung für einen solchen Körper definiert, könnten zukünftige HTTP-Erweiterungen den OPTIONS-Körper verwenden, um detailliertere Abfrageinformationen an den Server zu liefern. Ein Server, der solche Erweiterungen nicht unterstützt, kann (MAY) den Anfragekörper verwerfen.
Wenn der Request-URI ein Sternchen ("") ist, gilt die OPTIONS-Anfrage im Allgemeinen für den Server und nicht für eine bestimmte Ressource. Da die Kommunikationsoptionen eines Servers typischerweise von der Ressource abhängen, ist die ""-Anfrage nur als "Ping"- oder "No-Op"-Methode nützlich; sie tut nichts anderes, als dem Client zu ermöglichen, die Fähigkeiten des Servers zu testen. Dies kann beispielsweise verwendet werden, um die HTTP/1.1-Konformität eines Proxys (oder deren Fehlen) zu testen.
Wenn der Request-URI kein Sternchen ist, gilt die OPTIONS-Anfrage nur für die Optionen, die bei der Kommunikation mit dieser Ressource verfügbar sind.
Eine 200-Antwort sollte (SHOULD) alle Header-Felder enthalten, die optionale Funktionen anzeigen, wenn sie auf diese Ressource anwendbar sind (z.B. Allow), möglicherweise einschließlich Erweiterungen, die nicht durch diese Spezifikation definiert sind. Der Antwortkörper sollte (SHOULD), falls enthalten, ebenfalls Informationen über die Kommunikationsoptionen enthalten. Diese Spezifikation definiert nicht das Format dieses Körpers, könnte aber in zukünftigen HTTP-Erweiterungen definiert werden. Inhaltsverhandlung kann verwendet werden, um das geeignete Antwortformat auszuwählen. Wenn kein Antwortkörper enthalten ist, muss (MUST) die Antwort ein Content-Length-Feld mit einem Feldwert von "0" enthalten.
Das Max-Forwards-Anfrage-Header-Feld kann (MAY) verwendet werden, um eine Anfrage auf einen bestimmten Proxy in der Anfragekette auszurichten. Wenn ein Proxy eine OPTIONS-Anfrage empfängt, die die Weiterleitung der Anfrage erlaubt, muss (MUST) der Proxy das Max-Forwards-Feld überprüfen. Wenn der Wert des Max-Forwards-Feldes Null ("0") ist, darf (MUST NOT) der Proxy die Nachricht nicht weiterleiten; stattdessen sollte (SHOULD) der Proxy mit seinen eigenen Kommunikationsoptionen antworten. Wenn der Wert des Max-Forwards-Feldes eine ganze Zahl größer als Null ist, muss (MUST) der Proxy den Feldwert dekrementieren und die Anfrage an den nächsten Hop-Server weiterleiten. Wenn in der OPTIONS-Anfrage kein Max-Forwards-Feld vorhanden ist, darf (MUST NOT) der weiterleitende Proxy kein Max-Forwards-Feld hinzufügen.
9.3 GET
Die GET-Methode bedeutet das Abrufen aller Informationen (in Form einer Entität), die durch den Request-URI identifiziert werden. Wenn der Request-URI auf einen Datengenerierungsprozess verweist, sollten die generierten Daten als Entität in der Antwort zurückgegeben werden und nicht der Quelltext des Prozesses, es sei denn, dieser Text ist die Ausgabe des Prozesses.
Wenn die Anfragenachricht ein If-Modified-Since-, If-Unmodified-Since-, If-Match-, If-None-Match- oder If-Range-Header-Feld enthält, ändert sich die Semantik von GET zu "bedingtem GET" (conditional GET). Eine bedingte GET-Methode fordert an, dass die Entität nur unter den vom bedingten Header-Feld beschriebenen Umständen übertragen wird. Die bedingte GET-Methode soll unnötige Netzwerknutzung reduzieren, indem sie das Aktualisieren zwischengespeicherter Entitäten ermöglicht, ohne mehrere Anfragen oder die Übertragung von Daten zu erfordern, die der Client bereits besitzt.
Wenn die Anfragenachricht ein Range-Header-Feld enthält, ändert sich die Semantik von GET zu "partiellem GET" (partial GET). Ein partielles GET fordert nur einen Teil der Entität an, wie in Abschnitt 14.35 beschrieben. Die partielle GET-Methode soll unnötige Netzwerknutzung reduzieren, indem sie das Vervollständigen teilweise abgerufener Entitäten ermöglicht, ohne Daten zu übertragen, die der Client bereits besitzt.
Die Antwort auf eine GET-Anfrage ist cachebar, wenn und nur wenn sie die in Abschnitt 13 beschriebenen HTTP-Caching-Anforderungen erfüllt.
Siehe Abschnitt 15.1.3 für Sicherheitsüberlegungen zu den Methoden GET und HEAD.
9.4 HEAD
Die HEAD-Methode ist identisch mit GET, außer dass der Server in der Antwort keinen (MUST NOT) Nachrichtenkörper zurückgeben darf. Die in den HTTP-Headern der Antwort auf eine HEAD-Anfrage enthaltenen Metainformationen sollten (SHOULD) identisch mit den Informationen sein, die als Antwort auf eine GET-Anfrage gesendet würden. Diese Methode kann verwendet werden, um Metainformationen über die durch die Anfrage implizierte Entität zu erhalten, ohne den Entitätskörper selbst zu übertragen. Diese Methode wird häufig zum Testen der Gültigkeit, Zugänglichkeit und kürzlichen Änderung von Hypertext-Links verwendet.
Die Antwort auf eine HEAD-Anfrage kann (MAY) cachebar sein, da die in der Antwort enthaltenen Informationen verwendet werden können, um eine zuvor von dieser Ressource zwischengespeicherte Entität zu aktualisieren. Wenn die neuen Feldwerte anzeigen, dass die zwischengespeicherte Entität sich von der aktuellen Entität unterscheidet (wie durch Änderungen in Content-Length, Content-MD5, ETag oder Last-Modified angezeigt), muss (MUST) der Cache den Cache-Eintrag als veraltet behandeln.
9.5 POST
Die POST-Methode wird verwendet, um vom Origin-Server zu verlangen, die in der Anfrage enthaltene Entität als neuen Untergeordneten der durch den Request-URI identifizierten Ressource zu akzeptieren. POST ist so konzipiert, dass eine einheitliche Methode die folgenden Funktionen abdeckt:
- Annotation vorhandener Ressourcen;
- Veröffentlichung einer Nachricht auf einem schwarzen Brett, einer Newsgroup, einer Mailingliste oder einer ähnlichen Artikelgruppe;
- Bereitstellung eines Datenblocks (z.B. Formularübermittlung) an einen Datenverarbeitungsprozess;
- Erweiterung einer Datenbank durch eine Anfügeoperation.
Die tatsächlich durch die POST-Methode ausgeführte Funktion wird vom Server bestimmt und hängt normalerweise vom Request-URI ab. Die gepostete Entität ist diesem URI untergeordnet, so wie eine Datei einem Verzeichnis untergeordnet ist, das sie enthält, ein Nachrichtenartikel der Newsgroup untergeordnet ist, in der er gepostet wird, oder ein Datensatz einer Datenbank untergeordnet ist.
Die durch die POST-Methode ausgeführte Aktion führt möglicherweise nicht zu einer Ressource, die durch einen URI identifiziert werden kann. In diesem Fall ist 200 (OK) oder 204 (No Content) der geeignete Antwortstatus, je nachdem, ob die Antwort eine Entität enthält, die das Ergebnis beschreibt.
Wenn eine Ressource auf dem Origin-Server erstellt wurde, sollte (SHOULD) die Antwort 201 (Created) sein und eine Entität enthalten, die den Status der Anfrage beschreibt und auf die neue Ressource verweist, sowie einen Location-Header (siehe Abschnitt 14.30).
Antworten auf diese Methode sind nicht cachebar, es sei denn, die Antwort enthält geeignete Cache-Control- oder Expires-Header-Felder. Die 303 (See Other)-Antwort kann jedoch verwendet werden, um den Benutzeragenten anzuweisen, eine cachbare Ressource abzurufen.
POST-Anfragen müssen (MUST) die in Abschnitt 8.2 beschriebenen Nachrichtenübertragungsanforderungen befolgen.
Siehe Abschnitt 13.4 für Caching-Überlegungen zur POST-Methode.
9.6 PUT
Die PUT-Methode fordert an, dass die enthaltene Entität unter dem bereitgestellten Request-URI gespeichert wird. Wenn der Request-URI auf eine bereits vorhandene Ressource verweist, sollte die enthaltene Entität als modifizierte Version derjenigen betrachtet werden, die auf dem Origin-Server residiert. Wenn der Request-URI nicht auf eine vorhandene Ressource zeigt und dieser URI vom anfragenden Benutzeragenten als neue Ressource definiert werden kann, kann (can) der Origin-Server die Ressource mit diesem URI erstellen. Wenn eine neue Ressource erstellt wird, muss (MUST) der Origin-Server den Benutzeragenten über die 201 (Created)-Antwort informieren. Wenn eine vorhandene Ressource geändert wird, sollten (SHOULD) entweder die Antwortcodes 200 (OK) oder 204 (No Content) gesendet werden, um den erfolgreichen Abschluss der Anfrage anzuzeigen. Wenn die Ressource nicht mit dem Request-URI erstellt oder geändert werden kann, sollte (SHOULD) eine geeignete Fehlerantwort gegeben werden, die die Art des Problems widerspiegelt. Der Empfänger der Entität darf (MUST NOT) keine Content-*-Header (z.B. Content-Range) ignorieren, die er nicht versteht oder implementiert, und muss (MUST) in solchen Fällen eine 501 (Not Implemented)-Antwort zurückgeben.
Wenn die Anfrage durch einen Cache läuft und der Request-URI eine oder mehrere derzeit zwischengespeicherte Entitäten identifiziert, sollten (SHOULD) diese Einträge als veraltet behandelt werden. Antworten auf diese Methode sind nicht cachebar.
Der grundlegende Unterschied zwischen PUT- und POST-Anfragen spiegelt sich in der unterschiedlichen Bedeutung des Request-URI wider. Der URI in einer POST-Anfrage identifiziert die Ressource, die die enthaltene Entität verarbeiten wird. Diese Ressource kann ein Datenakzeptanzprozess, ein Gateway zu einem anderen Protokoll oder eine separate Entität sein, die Anmerkungen akzeptiert. Im Gegensatz dazu identifiziert der URI in einer PUT-Anfrage die mit der Anfrage enthaltene Entität - der Benutzeragent weiß, welcher URI beabsichtigt ist, und der Server darf (MUST NOT) nicht versuchen, die Anfrage auf eine andere Ressource anzuwenden. Wenn der Server möchte, dass die Anfrage auf einen anderen URI angewendet wird, muss (MUST) er eine 301 (Moved Permanently)-Antwort senden; der Benutzeragent kann (MAY) dann selbst entscheiden, ob er die Anfrage umleitet oder nicht.
Eine einzelne Ressource kann durch viele verschiedene URIs identifiziert werden. Zum Beispiel kann ein Artikel einen URI haben, um die "aktuelle Version" zu identifizieren, der sich von den URIs unterscheidet, die zur Identifizierung jeder bestimmten Version verwendet werden. In diesem Fall könnte eine PUT-Anfrage auf den generischen URI dazu führen, dass andere URIs vom Origin-Server definiert werden.
HTTP/1.1 definiert nicht, wie die PUT-Methode den Zustand des Origin-Servers beeinflusst.
PUT-Anfragen müssen (MUST) die in Abschnitt 8.2 beschriebenen Nachrichtenübertragungsanforderungen befolgen.
Sofern nicht anders angegeben, sollten (SHOULD) die Nebenwirkungen der PUT-Methode die gleichen sein wie beim Senden einer GET-Anfrage mit demselben Request-URI.
9.7 DELETE
Die DELETE-Methode fordert den Origin-Server auf, die durch den Request-URI identifizierte Ressource zu löschen. Diese Methode kann (MAY) auf dem Origin-Server durch menschliches Eingreifen (oder andere Mittel) überschrieben werden. Der Client kann nicht garantiert werden, dass die Operation ausgeführt wurde, selbst wenn der vom Origin-Server zurückgegebene Statuscode anzeigt, dass die Aktion erfolgreich abgeschlossen wurde. Der Server sollte (SHOULD NOT) jedoch keinen Erfolg anzeigen, es sei denn, er beabsichtigt zum Zeitpunkt der Antwortgebung, die Ressource zu löschen oder an einen unzugänglichen Ort zu verschieben.
Eine erfolgreiche Antwort sollte (SHOULD) 200 (OK) sein, wenn die Aktion wahrscheinlich erfolgreich war, 202 (Accepted), wenn die Aktion noch nicht ausgeführt wurde, oder 204 (No Content), wenn die Aktion ausgeführt wurde, aber die Antwort keine Entität enthält, selbst wenn es unmöglich ist zu wissen, ob die Operation erfolgreich ausgeführt wurde.
Wenn die Anfrage durch einen Cache läuft und der Request-URI eine oder mehrere derzeit zwischengespeicherte Entitäten identifiziert, sollten (SHOULD) diese Einträge als veraltet behandelt werden. Antworten auf diese Methode sind nicht cachebar.
9.8 TRACE
Die TRACE-Methode wird verwendet, um eine Remote-Anwendungsschicht-Loopback der Anfragenachricht entlang des Pfads zur Zielressource aufzurufen. Der endgültige Empfänger der Anfrage sollte (SHOULD) die empfangene Nachricht als Entitätskörper einer 200 (OK)-Antwort an den Client zurückspiegeln. Der endgültige Empfänger ist entweder der Origin-Server oder der erste Proxy oder Gateway, der eine Anfrage mit einem Max-Forwards-Wert von Null (0) empfängt (siehe Abschnitt 14.31). Eine TRACE-Anfrage darf (MUST NOT) keine Entität enthalten.
TRACE ermöglicht es dem Client zu sehen, was am anderen Ende der Anfragekette empfangen wird, und diese Daten für Test- oder Diagnoseinformationen zu verwenden. Der Wert des Via-Header-Feldes (Abschnitt 14.45) ist von besonderem Interesse, da er als Trace der Anfragekette fungiert. Die Verwendung des Max-Forwards-Headers ermöglicht es dem Client, die Länge der Anfragekette zu begrenzen, was zum Testen einer Proxy-Kette nützlich ist, die Nachrichten in einer Endlosschleife weiterleitet.
Wenn die Anfrage gültig ist, sollte (SHOULD) die Antwort die gesamte Anfragenachricht im Entitätskörper mit einem Content-Type von "message/http" enthalten. Antworten auf diese Methode dürfen (MUST NOT) nicht gecacht werden.
9.9 CONNECT
Diese Spezifikation reserviert den Methodennamen CONNECT für die Verwendung mit einem Proxy, der dynamisch zu einem Tunnel wechseln kann (z.B. SSL-Tunnel [44]).