RESTful API-Methoden; KOPF & OPTIONEN


92

Ich schreibe ein RESTful-API-Modul für eine Anwendung in PHP und bin ein bisschen gemischt mit den Verben HEADund OPTIONS.

  • OPTIONS  Wird verwendet, um die verfügbaren HTTP-Verben für eine bestimmte Ressource abzurufen?
  • HEAD Wird verwendet, um festzustellen, ob eine bestimmte Ressource verfügbar ist?

Wenn jemand diese Verben klären könnte, wäre das sehr dankbar.

* Die Klarstellung bezog sich auf RESTful-API-Architekturen, die HTTP-Verben neu verwenden. Ich habe , dass beide zu der Erkenntnis , da kam HEADund OPTIONSsoll nicht wiederverwendet werden, und stattdessen verhalten vorhersagbar wie jede HTTP - Anwendung sollte. Oh, wie wir in 2 Jahren wachsen.


wahrscheinlich, weil die HTTP-Spezifikationen im Web leicht verfügbar sind.
Gordon

@Gordon - Fair genug, und obwohl ich verstehe, dass RESTful API-Services die vorhandenen HTTP-Spezifikationen nutzen sollen, habe ich vermutlich eine teilweise Abweichung bei den Implementierungsdetails angenommen. Mein Fehler.
Dan Lugg

14
Spezifikationen für fast alles sind im Internet verfügbar. Fragen zu SO dienen der Klärung über die Dokumentation hinaus. Das passt dazu.
Andrew Ensley

Antworten:


60

Gemäß: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html

9.2 OPTIONEN

Die OPTIONS-Methode stellt eine Anforderung von Informationen zu den Kommunikationsoptionen dar, die in der durch den Anforderungs-URI angegebenen Anforderungs- / Antwortkette verfügbar sind. Mit dieser Methode kann der Client die mit einer Ressource verbundenen Optionen und / oder Anforderungen oder die Funktionen eines Servers ermitteln, ohne eine Ressourcenaktion zu implizieren oder einen Ressourcenabruf zu initiieren.

Antworten auf diese Methode können nicht zwischengespeichert werden.

Wenn die OPTIONS-Anforderung einen Entity-Body enthält (wie durch das Vorhandensein von Content-Length oder Transfer-Encoding angezeigt), MUSS der Medientyp durch ein Content-Type-Feld angegeben werden. Obwohl diese Spezifikation keine Verwendung für einen solchen Body definiert, verwenden zukünftige Erweiterungen von HTTP möglicherweise den OPTIONS-Body, um detailliertere Abfragen auf dem Server durchzuführen. Ein Server, der eine solche Erweiterung nicht unterstützt, kann den Anforderungshauptteil verwerfen.

Wenn der Anforderungs-URI ein Sternchen ("*") ist, soll die OPTIONS-Anforderung auf den Server im Allgemeinen und nicht auf eine bestimmte Ressource angewendet werden. Da die Kommunikationsoptionen eines Servers normalerweise von der Ressource abhängen, ist die Anforderung "*" nur als Methode vom Typ "Ping" oder "No-Op" nützlich. Es ermöglicht dem Client nicht, die Funktionen des Servers zu testen. Dies kann beispielsweise verwendet werden, um einen Proxy auf HTTP / 1.1-Konformität (oder deren Fehlen) zu testen.

Wenn der Anforderungs-URI kein Sternchen ist, gilt die OPTIONS-Anforderung nur für die Optionen, die bei der Kommunikation mit dieser Ressource verfügbar sind.

Eine Antwort von 200 sollte alle Headerfelder enthalten, die optionale Funktionen angeben, die vom Server implementiert wurden und auf diese Ressource anwendbar sind (z. B. Zulassen), möglicherweise einschließlich Erweiterungen, die nicht durch diese Spezifikation definiert sind. Der Antworttext sollte, falls vorhanden, auch Informationen zu den Kommunikationsoptionen enthalten. Das Format für einen solchen Körper wird durch diese Spezifikation nicht definiert, kann jedoch durch zukünftige Erweiterungen von HTTP definiert werden. Die Inhaltsverhandlung kann verwendet werden, um das geeignete Antwortformat auszuwählen. Wenn kein Antworttext enthalten ist, MUSS die Antwort ein Feld für die Inhaltslänge mit dem Feldwert "0" enthalten.

Das Feld Max-Forwards-Anforderungsheader kann verwendet werden, um auf einen bestimmten Proxy in der Anforderungskette abzuzielen. Wenn ein Proxy eine OPTIONS-Anforderung auf einem AbsolutURI empfängt, für die die Weiterleitung von Anforderungen zulässig ist, MUSS der Proxy nach einem Max-Forwards-Feld suchen. Wenn der Feldwert Max-Forwards Null ist ("0"), darf der Proxy die Nachricht NICHT weiterleiten. Stattdessen sollte der Proxy mit seinen eigenen Kommunikationsoptionen antworten. Wenn der Feldwert Max-Forwards eine Ganzzahl größer als Null ist, MUSS der Proxy den Feldwert verringern, wenn er die Anforderung weiterleitet. Wenn in der Anforderung kein Max-Forwards-Feld vorhanden ist, darf die weitergeleitete Anforderung KEIN Max-Forwards-Feld enthalten.

9.4 KOPF

Die HEAD-Methode ist identisch mit GET, außer dass der Server in der Antwort KEINEN Nachrichtentext zurückgeben darf. Die in den HTTP-Headern als Antwort auf eine HEAD-Anforderung enthaltenen Metainformationen MÜSSEN mit den Informationen identisch sein, die als Antwort auf eine GET-Anforderung gesendet wurden. Diese Methode kann verwendet werden, um Metainformationen über die durch die Anforderung implizierte Entität zu erhalten, ohne den Entitätskörper selbst zu übertragen. Diese Methode wird häufig zum Testen von Hypertext-Links auf Gültigkeit, Zugänglichkeit und aktuelle Änderungen verwendet.

Die Antwort auf eine HEAD-Anforderung kann in dem Sinne zwischengespeichert werden, dass die in der Antwort enthaltenen Informationen verwendet werden können, um eine zuvor zwischengespeicherte Entität von dieser Ressource zu aktualisieren. Wenn die neuen Feldwerte anzeigen, dass sich die zwischengespeicherte Entität von der aktuellen Entität unterscheidet (wie dies durch eine Änderung von Content-Length, Content-MD5, ETag oder Last-Modified angezeigt wird), MUSS der Cache den Cache-Eintrag als veraltet behandeln.


1
Vielen Dank an @sdolgy für das umfassende Angebot. Halten ( sollten ) in der Praxis jedoch viele erfolgreiche RESTful-API-Module alle diese HTTP-Standards ein, oder gibt es eine akzeptable schlanke Antwort für diese Vorgänge? Nicht aus Faulheit, sondern nur aus Neugier; Ich werde wahrscheinlich alles implementieren, was nötig ist, um zu haften.
Dan Lugg

2
Wenn Sie Ihre eigenen erstellen, von denen ich annehme, dass Sie es sind, sollten Sie versuchen, eine gewisse Übereinstimmung mit dokumentierten Standards aufrechtzuerhalten, um Ihnen das Leben zu erleichtern ... und das von Leuten, die Ihre API konsumieren ... folgen Sie nicht Microsoft. RFCs sind eine gute Sache, um sich auszurichten
sdolgy

Danke @sdolgy. Nachdem ich das verknüpfte Dokument informiert hatte, bemerkte ich am Ende das CONNECTVerb. Wäre es eine schlechte Wahl, diese Methode für die RESTful-Authentifizierung zu verwenden?
Dan Lugg

Nicht sicher, ob dies der beabsichtigte Zweck war. "Diese Spezifikation reserviert den Methodennamen CONNECT für die Verwendung mit einem Proxy, der dynamisch zu einem Tunnel wechseln kann (z. B. SSL-Tunneling [44])." ... kann hilfreich sein, um eine weitere Frage zu einer zu stellen der stackexchange.com Websites darüber ...
sdolgy

2
@DanLugg Ihre Anwendung wird möglicherweise nicht CONNECTfür SSL-Tunneling verwendet. Stellen Sie sich jedoch vor, was passieren würde, wenn ein Verbraucher Ihrer Anwendung einen Proxy hätte, der so implementiert ist, CONNECTwie er im RFC angegeben wurde. Die Anforderungen werden möglicherweise nicht an Ihre weitergeleitet Anwendung.
Steve Buzonas

79

OPTIONSMethode gibt Informationen zur API zurück (Methoden / Inhaltstyp)

HEADMethode gibt Informationen über die Ressource zurück (Version / Länge / Typ)

Serverantwort

OPTIONEN

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

KOPF

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 Identifizieren, welche HTTP-Methoden eine Ressource unterstützt, z. B. können wir sie LÖSCHEN oder über einen PUT aktualisieren?
  • HEADÜberprüfen, ob sich eine Ressource geändert hat. Dies ist nützlich, wenn Sie eine zwischengespeicherte Version einer Ressource verwalten
  • HEAD Abrufen von Metadaten über die Ressource, z. B. ihres Medientyps oder ihrer Größe, bevor ein möglicherweise kostspieliger Abruf durchgeführt wird
  • HEAD, OPTIONSTesten, ob eine Ressource vorhanden und zugänglich ist. Beispiel: Überprüfen von vom Benutzer übermittelten Links in einer Anwendung

Hier ist ein schöner und prägnanter Artikel darüber, wie HEAD und OPTIONS in die RESTful-Architektur passen.


9
Tolle Antwort, schade, dass es die Strafe für die verspätete Party zahlt. Die kopiert eingefügte akzeptierte Antwort beginnt nicht einmal, den Platz dieser Verben in einer RESTful-Architektur spezifisch anzusprechen.
Todd Menier

1
Dein Link ist tot. Hier ist der letzte Schnappschuss: web.archive.org/web/20160528151316/https://…
kolobok

29

OPTIONEN sagt Ihnen Dinge wie "Welche Methoden sind für diese Ressource zulässig?".

HEAD erhält den HTTP-Header, den Sie erhalten würden, wenn Sie eine GET-Anfrage stellen würden, jedoch ohne den Body. Auf diese Weise kann der Client die Caching-Informationen bestimmen, welcher Inhaltstyp zurückgegeben wird und welcher Statuscode zurückgegeben wird. Die Verfügbarkeit ist nur ein kleiner Teil davon.


Danke @Quentin; OPTIONSwar das, was ich mir vorgestellt habe, und eine solche Implementierung wird mit meinem bestehenden Ansatz einfach sein. Definiert gemäß dem RFC-Zitat von sdolgy OPTIONSkeinen Standard im Format. Wird angenommen, dass das Antwortformat mit anderen Antworten identisch ist? ( zB JSON, XML usw. )
Dan Lugg

@ Tomcat Zitieren des RFC: "Die Inhaltsverhandlung kann verwendet werden, um das entsprechende Antwortformat auszuwählen." Mit anderen Worten: Die Antwort sollte das sein, wonach die Anforderung im Header gefragt hat.
Gordon
Durch die Nutzung unserer Website bestätigen Sie, dass Sie unsere Cookie-Richtlinie und Datenschutzrichtlinie gelesen und verstanden haben.
Licensed under cc by-sa 3.0 with attribution required.