Ciekawe metody HTTP – część 2

Niedawno opisałem kilka ciekawszych metod HTTP. Dziś zabierzemy się za zupełnie egzotyczne metody. Będą to metody, których prawie nikt nie używa. Gorzej! Prawie nikt nie wie o ich istnieniu takich metod jak PATCH, LINK czy TRACE!

PATCH czyli częściowa aktualizacja

Na pierwszy ogień metoda PATCH, która wbrew pozorom będzie bardzo przydatna w API RESTowym. Metoda ta wprowadzona w RFC 5789 jest uzupełnieniem znanej nam metody PUT.

O ile znana nam metoda PUT wgrywa całe dane to PATCH służy do modyfikacji istniejącego zasobu. Przykładowo mając zasób oznaczający użytkownika:

http://moj.serwis.rest/api/user/1313

Możemy metodą PUT wgrać całkiem nowy zestaw danych, np. nowe imię, nazwisko i e-mail. Jeśli jednak chcemy dodać coś do zasobu (np. drugie imię) lub zmienić tylko jedną wartość (np. e-mail) wtedy używamy PATCH. Przykładowo

$ curl -i -X PATCH -d "middle_name=Leszek&e-mail=dont@mail.me" http://moj.serwis.rest/api/user/1313

Gdybyśmy w tym miejscu użyli PUT, skończylibyśmy z zasobem mającym tylko drugie imię i e-mail gdyż PUT zastępuje wszystkie dane nowymi. Moglibyśmy też otrzymać błąd np. 400 błędne wywołanie jeśli serwis wymaga danych, których nie podaliśmy.

Co ciekawe – specyfikacja nie określa jak mamy opisać nasze dane do modyfikacji. Format możemy sobie zdefiniować wedle uznania. Dane nie muszą być typu prostego. Mogą reprezentować jakąś akcję modyfikującą nasz zasób. Np.

$ curl -i -X PATCH -d "delete_field=middle_name&append_text=Notatka" http://moj.serwis.rest/api/user/1313

W powyższym przykładzie można się domyślić, że chcemy usunąć pole z drugim imieniem oraz dołączyć gdzieś, pewnie do całego zasobu, tekst o treści “Notatka”.

LINK i UNLINK czyli relacyjny HTTP

Przyznam, że sam nie wiedziałem o istnieniu tych metod. Specyfikacja w RFC 2068 je opisuje ale już późniejsze RFC opisujące HTTP pomijają te dwie metody. Szkoda, bo w skali ciekawych metod otrzymują u mnie 10 punktów (na 10).

Tak więc metoda LINK służy do… linkowania zasobów. Ale nie w treści dokumentów tylko w samym http. Załóżmy, że mamy listę obrazków a więc w treści dokumentu nie możemy dać linków do następnego i poprzedniego obrazu w galerii. Zamiast zmuszać nas do szukania danych gdzie indziej, api może pozwolić zapisać linki w nagłówkach (uwaga na escapeowanie cudzysłowów):

$ curl -i -X LINK \
  -H "Link: <http://rest.api/img/obraz665.jpg>; rel=\"prev\"" \
  -H "Link: <http://rest.api/img/obraz667.jpg>; rel=\"next\"" \
  http://rest.api/img/obraz666.jpg

Dodaliśmy dwa linki. Do poprzedniego i następnego obrazka. Korzystamy tu z relacyjności, którą opisywałem przy okazji linków semantycznych. Jak widać nazwy relacji przydają się też tutaj.

Jeśli teraz wywołamy GET lub HEAD, to w nagłówkach dostaniemy nasze linki:

$ curl -i -X HEAD http://rest.api/img/obraz666.jpg
HTTP/1.1 200 OK
... jakieś inne nagłówki ...
Link: <http://rest.api/img/obraz665.jpg>; rel="prev"
Link: <http://rest.api/img/obraz667.jpg>; rel="next"

Metoda LINK dodaje kolejne powiązania czyli działa tak, jak PATCH dla treści. Jeśli chcemy usunąć jakiś link, korzystamy z UNLINK. Przykładowo:

$ curl -i -X UNLINK \
  -H "Link: <http://rest.api/img/obraz667.jpg>; rel=\"next\"" \
  http://rest.api/img/obraz666.jpg

W ten sposób usunęliśmy link do następnego obrazu w galerii.

TRACE czyli niebezpieczny debugger

Metoda TRACE jest swoistym debugerem wbudowanym w protokół HTTP. Zadaniem serwera jest odesłać w odpowiedzi wszystkie nagłówki, które dostał. Możemy jej użyć aby sprawdzić co tak naprawdę wysłaliśmy do serwera:

$ curl -i -X TRACE -H "test: abc" http://localhost/
HTTP/1.1 200 OK
Date: Sat, 20 Dec 2014 02:32:12 GMT
Server: Apache
Transfer-Encoding: chunked
Content-Type: message/http

TRACE / HTTP/1.1
User-Agent: curl/7.28.1
Host: localhost
Accept: */*
test: abc

Widzimy w odpowiedzi serwera, że oprócz podanego przez nas nagłówka (test: abc) curl przedstawia się (User-Agent) oraz wysyła nagłówek Accept. Metoda może się przydać podczas testowania klienta serwisu RESTowego.

Niestety metoda TRACE stanowi zagrożenie. W sieci opisano metodę ataku na serwis z wykorzystaniem m.in. tej metody. Dlatego w nowszych instalacjach Apache jest ona domyślnie wyłączona.

Jeśli chcemy testować działanie TRACE, w naszej lokalnej instalacji Apache możemy włączyć ją poprzez ustawianie opcji:

TraceEnable on

Co dalej?

Jak widać protokół HTTP jest bogatym językiem komunikacji. Większość opisów tworzenia RESTful API pomija najciekawsze metody tego protokołu. Myślę, że z czasem programiści dojrzeją i zaczną w pełni korzystać z tych metod.

W opisach pominąłem dwie metody: DELETE – bo jej działanie jest oczywiste oraz CONNECT – ponieważ jest to bardzo rzadko używana metoda i nie ma nic wspólnego z serwisami, API i programowaniem. CONNECT jest używana do tunelowania połączeń. Będą nią zainteresowani bardziej admini niż developerzy.

Jest też cała grupa metod dla WebDAV. Te również pominąłem, jak też dodatkowe metody Microsoftu występujące tylko w ich serwerze IIS.

Jak zwykle IANA prowadzi pełną listę metod HTTP razem z linkami do ich specyfikacji.

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Pola, których wypełnienie jest wymagane, są oznaczone symbolem *