Metody RESTful API; GŁOWA I OPCJE


97

Piszę moduł RESTful API dla aplikacji w PHP i jestem trochę zmieszany z czasownikami HEADi OPTIONS.

  • OPTIONS  Służy do pobierania dostępnych czasowników HTTP dla danego zasobu?
  • HEAD Służy do określenia, czy dany zasób jest dostępny?

Gdyby ktoś mógł wyjaśnić * te czasowniki, byłoby to bardzo wdzięczne.

* Wyjaśnienie dotyczyło architektur RESTful API zmieniających przeznaczenie czasowników HTTP. Od tego czasu doszedłem do wniosku, że zarówno HEADi nieOPTIONS powinny być ponownie używane, a zamiast tego zachowywać się przewidywalnie tak, jak każda aplikacja HTTP powinna. Och, jak dorastamy za 2 lata.


prawdopodobnie dlatego, że specyfikacje HTTP są łatwo dostępne w sieci.
Gordon,

@Gordon - W porządku i chociaż rozumiem, że usługi RESTful API mają na celu wykorzystanie istniejących specyfikacji HTTP, przypuszczam, że założyłem pewne częściowe odchylenia od szczegółów implementacji. Mój błąd.
Dan Lugg,

15
Specyfikacje większości zadań są łatwo dostępne w sieci. Pytania dotyczące SO służą wyjaśnieniu poza dokumentacją. To pasuje do tego.
Andrew Ensley,

Odpowiedzi:


62

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

9.2 OPCJE

Metoda OPTIONS reprezentuje żądanie informacji o dostępnych opcjach komunikacji w łańcuchu żądań / odpowiedzi identyfikowanym przez URI żądania. Ta metoda umożliwia klientowi określenie opcji i / lub wymagań związanych z zasobem lub możliwościami serwera, bez narzucania działania związanego z zasobem lub inicjowania pobierania zasobu.

Odpowiedzi na tę metodę nie podlegają buforowaniu.

Jeśli żądanie OPTIONS zawiera treść encji (na co wskazuje obecność Content-Length lub Transfer-Encoding), wówczas typ nośnika MUSI być wskazany w polu Content-Type. Chociaż ta specyfikacja nie definiuje żadnego zastosowania takiej treści, przyszłe rozszerzenia HTTP mogą używać treści OPTIONS do wykonywania bardziej szczegółowych zapytań na serwerze. Serwer, który nie obsługuje takiego rozszerzenia, MOŻE odrzucić treść żądania.

Jeśli identyfikator URI żądania jest gwiazdką („*”), żądanie OPTIONS ma dotyczyć ogólnie serwera, a nie konkretnego zasobu. Ponieważ opcje komunikacji serwera zwykle zależą od zasobu, żądanie „*” jest przydatne tylko jako metoda typu „ping” lub „no-op”; nie robi nic poza umożliwieniem klientowi przetestowania możliwości serwera. Na przykład można tego użyć do przetestowania serwera proxy pod kątem zgodności z HTTP / 1.1 (lub jej braku).

Jeśli identyfikator URI żądania nie jest gwiazdką, żądanie OPTIONS dotyczy tylko opcji, które są dostępne podczas komunikacji z tym zasobem.

Odpowiedź 200 POWINNA zawierać wszystkie pola nagłówka, które wskazują opcjonalne funkcje zaimplementowane przez serwer i mające zastosowanie do tego zasobu (np. Zezwalaj), ewentualnie zawierające rozszerzenia nie zdefiniowane w tej specyfikacji. Ewentualna treść odpowiedzi POWINNA również zawierać informacje o opcjach komunikacji. Format takiej treści nie jest zdefiniowany w tej specyfikacji, ale może zostać zdefiniowany przez przyszłe rozszerzenia protokołu HTTP. Do wybrania odpowiedniego formatu odpowiedzi MOŻNA użyć negocjacji treści. Jeśli nie podano treści odpowiedzi, odpowiedź MUSI zawierać pole Content-Length z wartością pola „0”.

Pole nagłówka żądania Max-Forwards MOŻE być używane do kierowania na określone proxy w łańcuchu żądań. Gdy proxy otrzymuje żądanie OPTIONS na bezwzględnym adresie URL, dla którego dozwolone jest przekazywanie żądania, MUSI sprawdzić, czy jest pole Max-Forwards. Jeśli wartość pola Max-Forwards wynosi zero („0”), proxy NIE MOŻE przesyłać dalej wiadomości; zamiast tego serwer proxy POWINIEN odpowiadać własnymi opcjami komunikacji. Jeśli wartość pola Max-Forwards jest liczbą całkowitą większą od zera, proxy MUSI zmniejszyć wartość pola, gdy przekazuje żądanie dalej. Jeśli w żądaniu nie ma pola Max-Forwards, wówczas przesłane żądanie NIE MOŻE zawierać pola Max-Forwards.

9.4 GŁOWA

Metoda HEAD jest identyczna z metodą GET, z wyjątkiem tego, że serwer NIE MOŻE zwracać treści wiadomości w odpowiedzi. Metainformacja zawarta w nagłówkach HTTP w odpowiedzi na żądanie HEAD POWINNA być identyczna z informacjami przesłanymi w odpowiedzi na żądanie GET. Tej metody można użyć do uzyskania metainformacji o jednostce, której dotyczy żądanie, bez przenoszenia samej treści jednostki. Ta metoda jest często używana do testowania łączy hipertekstowych pod kątem ważności, dostępności i niedawnych modyfikacji.

Odpowiedź na żądanie HEAD MOŻE być zapisywalna w pamięci podręcznej w tym sensie, że informacje zawarte w odpowiedzi MOGĄ zostać wykorzystane do aktualizacji wcześniej zbuforowanej jednostki z tego zasobu. Jeśli nowe wartości pól wskazują, że jednostka buforowana różni się od jednostki bieżącej (na co wskazywałaby zmiana Content-Length, Content-MD5, ETag lub Last-Modified), wówczas pamięć podręczna MUSI traktować wpis pamięci podręcznej jako nieaktualny.


1
Dzięki @sdolgy za wyczerpującą wycenę; Jednak w praktyce nie ( powinno ) wiele udanych REST API moduły przylegają do wszystkich tych standardów HTTP, czy istnieje dopuszczalny szczupły odpowiedź dla tych operacji? Nie z lenistwa, ale po prostu z ciekawości; Prawdopodobnie zaimplementuję wszystko, co konieczne, aby się zastosować
Dan Lugg,

2
jeśli budujesz swój własny, a zakładam, że nim jesteś, powinieneś starać się zachować zgodność z udokumentowanymi standardami, aby ułatwić sobie życie ... a ludzi korzystających z twojego interfejsu API ... nie podążaj za Microsoft. RFC to dobra rzecz do dostosowania się
sdolgy

Dzięki @sdolgy. Po zapoznaniu się z połączonym dokumentem zauważyłem na końcu CONNECTczasownik. Czy używanie tej metody do uwierzytelniania RESTful byłoby złym wyborem?
Dan Lugg,

Nie jestem pewien, czy był to zamierzony cel „Ta specyfikacja rezerwuje nazwę metody CONNECT do użytku z proxy, które może dynamicznie przełączać się w tunel (np. Tunelowanie SSL [44]).” ... może być pomocne przy zadawaniu kolejnego pytania stron
stackexchange.com

2
@DanLugg Twoja aplikacja może nie wykorzystywać CONNECTtunelowania SSL, ale wyobraź sobie, co by się stało, gdyby konsument Twojej aplikacji miał proxy zaimplementowane CONNECTw sposób określony w specyfikacji RFC, żądania mogą nie zostać przekazane do Twojego podanie.
Steve Buzonas

92

OPTIONSmetoda zwraca informacje o API (metody / typ zawartości)

HEADmetoda zwraca informacje o zasobie (wersja / długość / typ)

Odpowiedź serwera

OPCJE

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

GŁOWA

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 Określenie, które metody HTTP obsługuje zasób, np. Czy możemy go USUNĄĆ lub zaktualizować za pośrednictwem PUT?
  • HEADSprawdzanie, czy zasób się zmienił. Jest to przydatne podczas utrzymywania wersji zasobu w pamięci podręcznej
  • HEAD Pobieranie metadanych dotyczących zasobu, np. Jego typu nośnika lub rozmiaru, przed dokonaniem potencjalnie kosztownego pobierania
  • HEAD, OPTIONSTestowanie, czy zasób istnieje i czy jest dostępny. Na przykład sprawdzanie poprawności linków przesłanych przez użytkowników w aplikacji

Oto ładny i zwięzły artykuł o tym, jak HEAD i OPTIONS pasują do architektury RESTful.


9
Świetna odpowiedź, szkoda, że ​​zapłaci karę za spóźnienie na przyjęcie. Zaakceptowana odpowiedź skopiowana wklejona nawet nie zaczyna zajmować się miejscem tych czasowników w architekturze RESTful.
Todd Menier

1
Twój link nie działa. Oto jego ostatnia migawka: web.archive.org/web/20160528151316/https
kolobok

31

OPCJE mówią rzeczy, takie jak „Jakie metody są dozwolone dla tego zasobu”.

HEAD pobiera nagłówek HTTP, który otrzymałeś, gdybyś wykonał żądanie GET, ale bez treści. Pozwala to klientowi określić informacje o pamięci podręcznej, jaki typ zawartości zostanie zwrócony, jaki kod stanu zostanie zwrócony. Dostępność to tylko niewielka część.


Dzięki @Quentin; OPTIONStak sobie wyobrażałem i takie wdrożenie będzie łatwe przy moim dotychczasowym podejściu. Zgodnie z cytatem RFC sdolgy, OPTIONSnie definiuje żadnego standardu w formacie. Czy zakłada się, że format odpowiedzi jest taki sam, jak innych odpowiedzi? ( np. JSON, XML itp. )
Dan Lugg,

@Tomcat Cytując RFC: „Negocjacja treści MOŻE być użyta do wybrania odpowiedniego formatu odpowiedzi”. Innymi słowy: odpowiedzią powinno być to, o co w nagłówku prosił Żądanie.
Gordon,
Korzystając z naszej strony potwierdzasz, że przeczytałeś(-aś) i rozumiesz nasze zasady używania plików cookie i zasady ochrony prywatności.
Licensed under cc by-sa 3.0 with attribution required.