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.