REST Najlepsze praktyki i wzorce w jezyku Java restja

Tytuł oryginału: RESTful Java Patterns and Best Practices

Tłumaczenie: Łukasz Piwko

ISBN: 978-83-283-0644-8

First published in the English language under the title
„RESTful Java Patterns and Best Practices” (9781783287963).

All rights reserved. No part of this book may be reproduced or transmitted in any form or by any means,
electronic or mechanical, including photocopying, recording or by any information storage retrieval system,
without permission from the Publisher.

Wszelkie prawa zastrzeżone. Nieautoryzowane rozpowszechnianie całości lub fragmentu niniejszej
publikacji w jakiejkolwiek postaci jest zabronione. Wykonywanie kopii metodą kserograficzną,
fotograficzną, a także kopiowanie książki na nośniku filmowym, magnetycznym lub innym powoduje
naruszenie praw autorskich niniejszej publikacji.

Wszystkie znaki występujące w tekście są zastrzeżonymi znakami firmowymi bądź towarowymi ich
właścicieli.

Autor oraz Wydawnictwo HELION dołożyli wszelkich starań, by zawarte w tej książce informacje były
kompletne i rzetelne. Nie biorą jednak żadnej odpowiedzialności ani za ich wykorzystanie, ani za związane
z tym ewentualne naruszenie praw patentowych lub autorskich. Autor oraz Wydawnictwo HELION nie
ponoszą również żadnej odpowiedzialności za ewentualne szkody wynikłe z wykorzystania informacji
zawartych w książce.

Wydawnictwo HELION
ul. Kościuszki 1c, 44-100 GLIWICE
tel. 32 231 22 19, 32 230 98 63
e-mail:

helion@helion.pl

WWW:

http://helion.pl (księgarnia internetowa, katalog książek)

Drogi Czytelniku!
Jeżeli chcesz ocenić tę książkę, zajrzyj pod adres
http://helion.pl/user/opinie/restja
Możesz tam wpisać swoje uwagi, spostrzeżenia, recenzję.

Printed in Poland.

Księgarnia internetowa

•

Lubię to! » Nasza społeczność

Spis treĂci

O autorce

PodziÚkowania

O recenzentach

WstÚp

Rozdziaï 1. Podstawy REST

Wprowadzenie do REST

REST i bezstanowoĂÊ

Model dojrzaïoĂci Richardsona

Poziom 0 — zdalne wywoïywanie procedur

Poziom 1 — zasoby REST

Poziom 2 — dodatkowe czasowniki HTTP

Poziom 3 — HATEOAS

Bezpieczeñstwo i idempotentnoĂÊ

Bezpieczeñstwo metod

IdempotentnoĂÊ metod

Zasady projektowe dotyczÈce budowy usïug typu RESTful

Wyznaczenie identyfikatorów URI zasobów

Identyfikacja metod obsïugiwanych przez zasób

Czasowniki HTTP w REST

PUT czy POST

Identyfikacja róĝnych reprezentacji zasobu

Implementowanie API

API Javy dla usïug RESTful (JAX-RS)

Kup książkę

Poleć książkę

REST. Najlepsze praktyki i wzorce w jĊzyku Java

Wdraĝanie usïug typu RESTful

Testowanie usïug typu RESTful

API klienta w JAX-RS 2.0

Uzyskiwanie dostÚpu do zasobów RESTful

Inne narzÚdzia

Najlepsze praktyki projektowania zasobów

Zalecana lektura

Podsumowanie

Rozdziaï 2. Projektowanie zasobów

Rodzaje odpowiedzi REST

Negocjacja treĂci

Negocjacja treĂci przy uĝyciu nagïówków HTTP

Negocjacja treĂci poprzez adres URL

Dostawcy jednostek i róĝne reprezentacje

StreamingOutput

ChunkedOutput

Jersey i JSON

Wersjonowanie API

OkreĂlanie wersji w identyfikatorze URI

Numer wersji w parametrze zapytaniowym ĝÈdania

OkreĂlanie numeru wersji w nagïówku Accept

Kody odpowiedzi i wzorce REST

Zalecana lektura

Podsumowanie

Rozdziaï 3. Bezpieczeñstwo i wykrywalnoĂÊ

Rejestrowanie informacji w API REST

Najlepsze praktyki rejestrowania informacji w API REST

Sprawdzanie poprawnoĂci usïug REST

Obsïuga wyjÈtków i kodów odpowiedzi

zwiÈzanych z weryfikacjÈ poprawnoĂci danych

Obsïuga bïÚdów w usïugach typu RESTful

Uwierzytelnianie i autoryzacja

Co to jest uwierzytelnianie

Co to jest autoryzacja

Róĝnice miÚdzy OAuth 2.0 i OAuth 1.0

Tokeny odĂwieĝania a tokeny dostÚpu

Najlepsze praktyki przy implementacji OAuth w API REST

OpenID Connect

Elementy architektury REST

Zalecana lektura

Podsumowanie

Kup książkę

Poleć książkę

Spis treĞci

Rozdziaï 4. Projektowanie wydajnych rozwiÈzañ

Zasady buforowania

Szczegóïy buforowania

Typy nagïówków buforowania

Nagïówek Cache-Control i dyrektywy

Nagïówek Cache-Control i API REST

Znaczniki ETag

API REST Facebooka i nagïówki ETag

Asynchroniczne i dïugotrwaïe operacje w REST

Asynchroniczne przetwarzanie ĝÈdañ i odpowiedzi

Najlepsze praktyki pracy z zasobami asynchronicznymi

Wysyïanie kodu statusu 202 Accepted

Ustawianie terminu wygaĂniÚcia dla obiektów w kolejce

Asynchroniczne obsïugiwanie zadañ przy uĝyciu kolejek wiadomoĂci

Metoda HTTP PATCH i czÚĂciowe aktualizacje

JSON Patch

Zalecana lektura

Podsumowanie

Rozdziaï 5. Zaawansowane zasady projektowania

Techniki ograniczania liczby ĝÈdañ 80

Ukïad projektu

Szczegóïowa analiza przykïadu ograniczania liczby ĝÈdañ 82
Najlepsze praktyki pozwalajÈce uniknÈÊ przekroczenia limitu ĝÈdañ przez klienty

Stronicowanie odpowiedzi

Rodzaje stronicowania

Ukïad projektu

Internacjonalizacja i lokalizacja

Róĝne tematy

HATEOAS

API REST portalu PayPal i HATEOAS

REST i rozszerzalnoĂÊ 94
Inne tematy zwiÈzane z API REST

Testowanie usïug typu RESTful

Zalecana lektura

Podsumowanie

Rozdziaï 6. Nowe standardy i przyszïoĂÊ technologii REST

API reagujÈce na bieĝÈco

Sondowanie

Model PuSH — PubSubHubbub

Model strumieniowania

100

Uchwyty sieciowe

103

Gniazda sieciowe

104

Kup książkę

Poleć książkę

REST. Najlepsze praktyki i wzorce w jĊzyku Java

Inne API i technologie do komunikacji na bieĝÈco

106

XMPP

106

BOSH poprzez XMPP

107

Porównanie uchwytów sieciowych, gniazd sieciowych i zdarzeñ

wysyïanych przez serwer

107

REST i mikrousïugi

108

Prostota

108

WyodrÚbnienie problemów

108

SkalowalnoĂÊ

109

Wyraěny podziaï funkcjonalnoĂci

109

NiezaleĝnoĂÊ od jÚzyka programowania

109

Zalecana lektura

109

Podsumowanie

110

Dodatek A

111

PrzeglÈd API REST portalu GitHub

111

Pobieranie informacji z portalu GitHub

112

Czasowniki i akcje zasobów

113

Wersjonowanie

113

Obsïuga bïÚdów

113

Ograniczanie liczby ĝÈdañ

114

PrzeglÈd API Graph portalu Facebook

114

Czasowniki i czynnoĂci zasobów

116

Wersjonowanie

116

Obsïuga bïÚdów

116

Ograniczanie liczby ĝÈdañ

117

PrzeglÈd API portalu Twitter

117

Czasowniki i dziaïania na zasobach

118

Wersjonowanie

119

Obsïuga bïÚdów

119

Zalecana lektura

119

Podsumowanie

119

Skorowidz

121

Kup książkę

Poleć książkę

Podstawy REST

Usïugi sieciowe w tradycyjnej technologii SOA, umoĝliwiajÈce zróĝnicowanÈ komunikacjÚ
miÚdzy aplikacjami, istniejÈ juĝ od pewnego czasu. Jednym ze sposobów obsïugi tej komuni-
kacji jest uĝycie technologii Simple Object Access Protocol (SOAP) i Web Service Description
Language (WSDL). SÈ to standardy oparte na formacie XML doskonale sprawdzajÈce siÚ, gdy
miÚdzy usïugami jest Ăcisïy kontakt. Ale nastaïa era usïug rozproszonych. Teraz róĝne klienty
z internetu, urzÈdzenia przenoĂne, jak równieĝ inne usïugi (wewnÚtrzne i zewnÚtrzne) mogÈ
uĝywaÊ interfejsów API udostÚpnianych przez róĝnych dostawców i róĝne platformy open
source. To sprawia, ĝe potrzebne sÈ technologie ïatwej wymiany informacji miÚdzy usïugami
rozproszonymi w róĝnych miejscach, z przewidywalnymi, solidnymi, ĂciĂle zdefiniowanymi
interfejsami.

Protokóï HTTP 1.1, zdefiniowany w dokumencie RFC 2616, jest powszechnie uĝywany w roz-
proszonych systemach hipermedialnych. Technologia Representational State Transfer (REST)
bazuje na HTTP i moĝe byÊ uĝywana wszÚdzie tam, gdzie ten protokóï. W tym rozdziale przed-
stawione sÈ podstawowe wiadomoĂci na temat projektowania usïug typu RESTful oraz uĝywa-
nia takich usïug za pomocÈ standardowych interfejsów API Javy.

W rozdziale omówiono nastÚpujÈce zagadnienia:

Wprowadzenie do technologii REST.

Bezpieczeñstwo i idempotentnoĂÊ.

Zasady projektowe dotyczÈce budowy usïug typu RESTful.

Standardowe API Javy dla usïug typu RESTful.

Najlepsze techniki projektowania usïug typu RESTful.

Kup książkę

Poleć książkę

REST. Najlepsze praktyki i wzorce w jĊzyku Java

Wprowadzenie do REST

REST to styl architektoniczny zgodny z takimi standardami sieciowymi jak czasowniki HTTP
i identyfikatory URI. ObowiÈzujÈ w nim nastÚpujÈce zasady:

Wszystkie zasoby okreĂla identyfikator URI.

Kaĝdy zasób moĝe mieÊ liczne reprezentacje.

Kaĝdy zasób moĝna pobraÊ, zmodyfikowaÊ, utworzyÊ i usunÈÊ standardowymi
metodami HTTP.

Na serwerze nie sÈ przechowywane ĝadne informacje o stanie.

REST i bezstanowoĂÊ

W REST obowiÈzuje zasada bezstanowoĂci. Kaĝde ĝÈdanie przesyïane przez klienta do ser-
wera musi zawieraÊ wszystkie informacje potrzebne do obsïugi tego zdarzenia. To poprawia
widocznoĂÊ, niezawodnoĂÊ i skalowalnoĂÊ ĝÈdañ.

Poprawa widocznoĂci wynika z tego, ĝe system monitorujÈcy ĝÈdania nie musi szukaÊ szcze-
góïów poza ĝÈdaniami. NiezawodnoĂÊ poprawia siÚ dziÚki wyeliminowaniu punktów kontrol-
nych i wznowienia w przypadku czÚĂciowych niepowodzeñ operacji. Poprawa skalowalnoĂci
jest efektem zwiÚkszenia liczby ĝÈdañ, które jest w stanie przetworzyÊ serwer, co jest moĝliwe
dziÚki temu, ĝe serwer nie musi przechowywaÊ informacji o stanie.

Roy Fielding napisaï doktorat na temat stylu architektonicznego REST, w którym szczegóïowo opisaï bez-
stanowoĂÊ tej technologii. WiÚcej informacji na ten temat moĝna znaleěÊ pod adresem

http://www.ics.

uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

To sÈ podstawowe wiadomoĂci o technologii REST. Teraz zajmiemy siÚ róĝnymi poziomami
dojrzaïoĂci i zobaczymy, gdzie poĂród nich mieĂci siÚ ta technologia.

Model dojrzaïoĂci Richardsona

Model dojrzaïoĂci Richardsona to opracowany przez Leonarda Richardsona model opisujÈ-
cy podstawy REST pod wzglÚdem zasobów, czasowników i hipermediów. Punktem poczÈt-
kowym tego modelu jest wykorzystanie HTTP jako warstwy transportowej. Ukazuje to poniĝ-
szy schemat.

Kup książkę

Poleć książkę

Rozdziaá 1. • Podstawy REST

Poziom 0 — zdalne wywoïywanie procedur

Do poziomu 0 zalicza siÚ przesyïanie danych przy uĝyciu technologii SOAP i XML-RPC jako
POX (ang. Plain Old XML — zwykïy XML). Uĝywana jest tylko metoda

POST

. Jest to najprost-

szy sposób budowania aplikacji SOA z jednÈ metodÈ

POST

i przy uĝyciu formatu XML do ko-

munikacji miÚdzy usïugami.

Poziom 1 — zasoby REST

Na poziomie 1 uĝywane sÈ metody

POST

, a zamiast funkcji i przekazywania argumentów wy-

korzystuje siÚ identyfikatory URI REST. Zatem nadal uĝywana jest tylko jedna metoda HTTP.
ZaletÈ tego poziomu w stosunku do zerowego jest podziaï zïoĝonej funkcjonalnoĂci na kilka
zasobów za pomocÈ jednej metody

POST

sïuĝÈcej do komunikacji miÚdzy usïugami.

Poziom 2 — dodatkowe czasowniki HTTP

Na poziomie drugim jest wiÚcej czasowników, np.

GET

HEAD

DELETE

PUT

i oczywiĂcie

POST

Poziom ten reprezentuje rzeczywisty przypadek uĝycia technologii REST, w której wykorzy-
stuje siÚ róĝne czasowniki HTTP do wykonywania róĝnych ĝÈdañ, a system moĝe zawieraÊ
wiele zasobów.

Kup książkę

Poleć książkę

REST. Najlepsze praktyki i wzorce w jĊzyku Java

Poziom 3 — HATEOAS

HATEOAS (ang. Hypermedia as the Engine of Application State — hipermedia jako mecha-
nizm obsïugi stanu aplikacji) reprezentuje najwyĝszy stopieñ dojrzaïoĂci w modelu Richard-
sona. Odpowiedzi na ĝÈdania klientów zawierajÈ elementy hipermedialne, przy uĝyciu których
klient moĝe zdecydowaÊ, co robiÊ dalej. Zasady te uïatwiajÈ wykrywanie usïug i sprawiajÈ, ĝe
odpowiedzi sÈ bardziej zrozumiaïe. ToczÈ siÚ dyskusje na temat tego, czy HATEOAS rzeczy-
wiĂcie speïnia wymagania RESTful, poniewaĝ reprezentacja zawiera o wiele wiÚcej informa-
cji niĝ tylko opis zasobu. W rozdziale 5. przedstawiam parÚ przykïadów pokazujÈcych, jak za-
implementowano HATEOAS jako czÚĂÊ API niektórych platform, np. PayPal.

W nastÚpnym podrozdziale wyjaĂniam pojÚcia bezpieczeñstwo i idempotentnoĂÊ, które sÈ bar-
dzo waĝne w usïugach RESTful.

Bezpieczeñstwo i idempotentnoĂÊ

W poniĝszych dwóch podrozdziaïach dokïadniej wyjaĂniam znaczenie bezpieczeñstwa i idem-
potentnoĂci metod.

Bezpieczeñstwo metod

Bezpieczna metoda to taka, która nie zmienia stanu na serwerze. Warunek ten speïnia na przy-
kïad metoda

GET /v1/coffees/orders/1234

Bezpieczne metody, do których zaliczajÈ siÚ GET i HEAD, moĝna buforowaÊ.
Metoda PUT nie jest bezpieczna, poniewaĝ tworzy lub modyfikuje zasoby na serwerze. To samo dotyczy
metody POST. Z kolei metoda DELETE nie jest bezpieczna, poniewaĝ usuwa zasoby z serwera.

IdempotentnoĂÊ metod

Metoda idempotentna to taka, która zwraca taki sam wynik niezaleĝnie od tego, ile razy zosta-
nie wywoïana.

Metoda GET jest idempotentna, poniewaĝ niezaleĝnie od tego, ile razy siÚ jÈ wywoïa, zawsze zwraca
takÈ samÈ odpowiedě.
Metoda PUT teĝ jest idempotentna, poniewaĝ wielokrotne jej wywoïanie powoduje aktualizacjÚ tego
samego zasobu i nie zmienia to wyniku.

Kup książkę

Poleć książkę

Rozdziaá 1. • Podstawy REST

Metoda POST nie jest idempotentna, poniewaĝ jej wielokrotne wywoïanie moĝe dawaÊ róĝne skutki
i powodowaÊ powstanie wielu zasobów. Metoda DELETE jest idempotentna, gdyĝ usuniÚty zasób znika
i powtórne wywoïanie tej samej metody niczego nie zmieni.

Zasady projektowe dotyczÈce budowy usïug

typu RESTful

Poniĝej w punktach przedstawiam proces projektowania, tworzenia i testowania usïug typu
RESTful. Dalej znajduje siÚ dokïadniejszy opis kaĝdego z tych etapów:

Wyznaczenie identyfikatorów URI zasobów.
Polega na wybraniu rzeczowników do reprezentowania zasobu.

Identyfikacja metod obsïugiwanych przez zasób.
Polega na wybraniu metod HTTP do wykonywania operacji CRUD (ang. create,
read, update, delete — utworzenie, odczytanie, aktualizacja, usuniÚcie).

Identyfikacja róĝnych reprezentacji zasobu.
Polega na wybraniu, czy zasób bÚdzie reprezentowany w formacie JSON, XML,
HTML, czy tekstowym.

Implementacja usïug RESTful przy uĝyciu API JAX-RS.
Interfejs API naleĝy zaimplementowaÊ na podstawie specyfikacji JAX-RS.

Wdroĝenie usïug RESTful.
Wdroĝenie usïugi w kontenerze aplikacji, np. Tomcat, GlassFish lub WildFly.
Na przykïadach pokazujÚ, jak tworzy siÚ pliki WAR, i prezentujÚ sposób wdroĝenia
na serwerze GlassFish 4.0. Poza tym przedstawiony przykïad dziaïa w kaĝdym
kontenerze zgodnym z Java EE 7.

Testowanie usïug RESTful.
Polega na napisaniu API klienta do testowania usïug lub uĝyciu narzÚdzi cURL
albo przeglÈdarkowych do testowania ĝÈdañ REST.

Wyznaczenie identyfikatorów URI zasobów

Zasoby RESTful sÈ identyfikowane przez identyfikatory URI. DziÚki temu technologia REST
jest rozszerzalna.

Poniĝsza tabela zawiera przykïady identyfikatorów URI, które mogÈ reprezentowaÊ róĝne za-
soby w systemie.

Kup książkę

Poleć książkę

REST. Najlepsze praktyki i wzorce w jĊzyku Java

URI

Opis

/v1/library/books

Moĝliwa reprezentacja kolekcji zasobów ksiÈĝkowych w bibliotece.

/v1/library/books/isbn/12345678

Moĝliwa reprezentacja jednej ksiÈĝki identyfikowanej przez numer
ISBN 123456.

/v1/coffees

Moĝliwa reprezentacja wszystkich kaw sprzedanych w kawiarni.

/v1/coffees/orders

Moĝliwa reprezentacja wszystkich zamówionych kaw w kawiarni.

/v1/coffees/orders/123

Moĝliwa reprezentacja pojedynczego zamówienia kawy
o identyfikatorze 123.

/v1/users/1235

Moĝliwa reprezentacja uĝytkownika o identyfikatorze w systemie 1235.

/v1/users/5034/books

Moĝliwa reprezentacja wszystkich ksiÈĝek uĝytkownika
o identyfikatorze 5034.

Wszystkie przedstawione identyfikatory sÈ zbudowane wg jasnego wzorca, który klient moĝe
bez trudu zinterpretowaÊ. Wszystkie te zasoby mogÈ mieÊ liczne reprezentacje, np. w forma-
cie JSON, XML, HTML lub tekstowym, i moĝna nimi zarzÈdzaÊ za pomocÈ metod

GET

PUT

POST

DELETE

Identyfikacja metod obsïugiwanych przez zasób

Czasowniki HTTP stanowiÈ waĝny skïadnik jednolitego ograniczenia interfejsu, które definiu-
je zwiÈzek miÚdzy czynnoĂciami opisywanymi przez dany czasownik w stosunku do opisanego
za pomocÈ rzeczowników zasobu REST.

Poniĝsza tabela zawiera zestawienie metod HTTP i opis powodowanych przez nie zdarzeñ oraz
prosty przykïad kolekcji ksiÈĝek w bibliotece.

Metoda HTTP URI zasobu

Opis

GET

/library/books

Pobiera listÚ ksiÈĝek.

GET

/library/books/isbn/12345678

Pobiera ksiÈĝkÚ o numerze ISBN 12345678.

POST

/library/books

Tworzy nowe zamówienie ksiÈĝki.

DELETE

/library/books/isbn/12345678

Usuwa ksiÈĝkÚ o numerze ISBN 12345678.

PUT

/library/books/isbn/12345678

Aktualizuje ksiÈĝkÚ o numerze ISBN 12345678.

PATCH

/library/books/isbn/12345678

CzÚĂciowo aktualizuje ksiÈĝkÚ o numerze ISBN 12345678.

W kolejnym podrozdziale znajduje siÚ opis zastosowania kaĝdego z czasowników HTTP w kon-
tekĂcie REST.

Kup książkę

Poleć książkę

Rozdziaá 1. • Podstawy REST

Czasowniki HTTP w REST

Czasowniki HTTP stanowiÈ dla serwera informacjÚ o tym, co ma zrobiÊ z otrzymanymi danymi.

GET

GET

to najprostsza metoda HTTP pozwalajÈca uzyskaÊ dostÚp do zasobu. Gdy klient kliknie

adres URL w przeglÈdarce internetowej, aplikacja ta wysyïa ĝÈdanie

GET

pod ten wïaĂnie ad-

res. Metoda

GET

jest bezpieczna i idempotentna. ¿Èdania wysyïane tÈ metodÈ sÈ buforowane

i mogÈ zawieraÊ parametry.

Poniĝej znajduje siÚ proste ĝÈdanie

GET

pobierajÈce wszystkich aktywnych uĝytkowników:

curl http://api.foo.com/v1/users/12345?active=true

POST

Metoda

POST

sïuĝy do tworzenia zasobów. ¿Èdania wysyïane przy uĝyciu tej metody nie sÈ

idempotentne ani bezpieczne. Wielokrotne wywoïania mogÈ spowodowaÊ utworzenie wielu
zasobów.

¿Èdanie

POST

powinno powodowaÊ uniewaĝnienie odpowiedniego elementu w buforze, jeĂli

taki istnieje. W ĝÈdaniach

POST

nie zaleca siÚ stosowania parametrów zapytaniowych.

Poniĝej znajduje siÚ ĝÈdanie utworzenia uĝytkownika:

curl –X POST -d'{"name":"Jan Kowalski","username":"jkow", "phone":
"412-344-5644"}' http://api.foo.com/v1/users

PUT

Metoda

PUT

sïuĝy do aktualizowania zasobów. Jest ona idempotentna, ale nie jest bezpieczna.

Wielokrotne ĝÈdania tego typu powinny dawaÊ taki sam efekt w postaci zaktualizowania zasobu.

¿Èdania

PUT

powinny uniewaĝniaÊ zawartoĂÊ bufora, jeĂli taka istnieje.

Poniĝej znajduje siÚ przykïad ĝÈdania

PUT

aktualizujÈcego uĝytkownika:

curl –X PUT -d'{ "phone":"413-344-5644"}'
http://api.foo.com/v1/users

DELETE

Metoda

DELETE

sïuĝy do usuwania zasobów. Jest idempotentna, ale nie jest bezpieczna. Idem-

potentnoĂÊ wynika z tego, ĝe zgodnie ze specyfikacjÈ RFC 2616 skutki uboczne dowolnej wiÚk-
szej od zera liczby ĝÈdañ sÈ takie same jak jednego ĝÈdania. Oznacza to, ĝe po usuniÚciu zaso-
bu kolejne wywoïania metody

DELETE

nic nie zmieniajÈ.

Kup książkę

Poleć książkę

REST. Najlepsze praktyki i wzorce w jĊzyku Java

Poniĝej znajduje siÚ przykïadowe ĝÈdanie usuwajÈce uĝytkownika:

curl –X DELETE http://foo.api.com/v1/users/1234

HEAD

¿Èdania typu

HEAD

sÈ podobne do

GET

. Róĝnica miÚdzy nimi polega na tym, ĝe w odpowiedzi

na ĝÈdanie

HEAD

zwracane sÈ tylko nagïówki HTTP, bez treĂci. Metoda

HEAD

jest idempotentna

i bezpieczna.

Poniĝej znajduje siÚ przykïadowe ĝÈdanie

HEAD

wysyïane za pomocÈ narzÚdzia cURL:

curl –X HEAD http://foo.api.com/v1/users

JeĂli zasób jest duĝy, to za pomocÈ ĝÈdania HEAD moĝna sprawdziÊ, czy coĂ siÚ w nim zmieniïo, zanim siÚ
je pobierze przy uĝyciu ĝÈdania GET.

PUT czy POST

Zgodnie z dokumentem RFC róĝnica miÚdzy metodami

PUT

POST

dotyczy identyfikatora URI

ĝÈdania. W metodzie

POST

przesïany identyfikator URI definiuje jednostkÚ, która ma obsïuĝyÊ

ĝÈdanie. W ĝÈdaniu

PUT

natomiast identyfikator URI zawiera tÚ jednostkÚ.

A zatem

POST /v1/coffees/orders

oznacza utworzenie nowego zasobu i zwrócenie opisujÈcego

go identyfikatora.

PUT /v1/coffees/orders/1234

oznacza natomiast aktualizacjÚ zasobu o iden-

tyfikatorze

1234

, jeĂli taki istnieje. JeĂli nie ma takiego zasobu, zostanie utworzone nowe za-

mówienie, do którego identyfikacji zostanie uĝyty URI

orders/1234

Zarówno metody PUT, jak i POST moĝna uĝywaÊ do tworzenia i aktualizacji zasobów. Wybór jednej z nich
zaleĝy gïównie od tego, czy potrzebna jest idempotentnoĂÊ metody, oraz od lokalizacji zasobu.

W nastÚpnym podrozdziale dowiesz siÚ, jak identyfikowaÊ róĝne reprezentacje zasobu.

Identyfikacja róĝnych reprezentacji zasobu

Zasoby RESTful sÈ jednostkami abstrakcyjnymi, które przed przesïaniem do klienta trzeba pod-
daÊ serializacji do jakiegoĂ reprezentacyjnego formatu. WĂród najczÚĂciej uĝywanych repre-
zentacji moĝna wymieniÊ XML, JSON, HTML i zwykïy tekst. Zasób moĝe dostarczaÊ kliento-
wi reprezentacjÚ w zaleĝnoĂci od tego, co klient ten jest w stanie przyjÈÊ. Klient moĝe okreĂliÊ
preferowane przez siebie jÚzyki i typy mediów. Nazywa siÚ to negocjacjÈ treĂci i zostaïo szcze-
góïowo opisane w rozdziale 2.

Kup książkę

Poleć książkę

Rozdziaá 1. • Podstawy REST

Implementowanie API

Wiesz juĝ mniej wiÚcej, jak projektowaÊ zasoby RESTful i jakich czasowników HTTP uĝywaÊ
do wykonywania róĝnych dziaïañ na tych zasobach, wiÚc moĝemy przejĂÊ do kwestii imple-
mentowania API i budowania usïugi typu RESTful. Gïównym tematem tego podrozdziaïu jest:

API Javy dla usïug RESTful (JAX-RS).

API Javy dla usïug RESTful (JAX-RS)

API Javy dla usïug RESTful sïuĝy do budowania i rozwijania aplikacji wg zasad technologii
REST. Przy uĝyciu JAX-RS moĝna udostÚpniaÊ obiekty Javy jako usïugi sieciowe typu RESTful,
które sÈ niezaleĝne od podstawowej technologii i uĝywajÈ prostego API opartego na adnotacjach.

Najnowsza wersja specyfikacji to JAX-RS 2.0. Od wersji JAX-RS 1.0 róĝni siÚ przede wszystkim:

narzÚdziami do sprawdzania poprawnoĂci ziaren,

obsïugÈ API klienta,

moĝliwoĂciÈ wykonywania wywoïañ asynchronicznych.

Implementacja specyfikacji JAX-RS nazywa siÚ Jersey.

Wszystkie wymienione tematy zostaïy szczegóïowo opisane w kolejnych rozdziaïach. Przed-
stawiam prosty przykïad kawiarni, w którym moĝna utworzyÊ zasób REST o nazwie

Coffees-

Resource

o nastÚpujÈcych umiejÚtnoĂciach:

podanie szczegóïów zïoĝonych zamówieñ,

tworzenie nowych zamówieñ,

sprawdzenie informacji o wybranym zamówieniu.

Tworzenie zasobu RESTful zaczniemy od utworzenia obiektu Javy o nazwie

CoffeesResource

Poniĝej znajduje siÚ przykïad zasobu JAX-RS:

@Path("v1/coffees")
public class CoffeesResource {

@GET
@Path("orders")
@Produces(MediaType.APPLICATION_JSON)
public List<Coffee> getCoffeeList( ){
// implementacja

}

1. W powyĝszym kodzie zostaï utworzony niewielki obiekt Javy o nazwie

CoffeesResource

. KlasÚ tÚ opatrzyïam adnotacjÈ

@Path("v1/coffees")

okreĂlajÈcÈ

ĂcieĝkÚ URI, dla której klasa ta obsïuguje ĝÈdania.

Kup książkę

Poleć książkę

REST. Najlepsze praktyki i wzorce w jĊzyku Java

2. NastÚpnie definiujemy metodÚ o nazwie

getCoffeeList()

. Ma ona nastÚpujÈce

adnotacje:

@GET

: oznacza, ĝe metoda reprezentuje ĝÈdanie HTTP

GET

@PATH

: w tym przypadku ĝÈdania

GET

zasobu

v1/coffees/orders

bÚdÈ

obsïugiwane przez metodÚ

getCoffeeList()

@Produces

: definiuje typy mediów zwracane przez ten zasób. W omawianym

przykïadzie okreĂlono typ mediów

MediaType.APPLICATION_JSON

, którego

wartoĂÊ to

application/json

3. Inna metoda tworzÈca zamówienie wyglÈda tak:

@POST
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
@ValidateOnExecution
public Response addCoffee(@Valid Coffee coffee) {
// implementacja
}

Jest to metoda o nazwie

addCoffee()

zawierajÈca nastÚpujÈce adnotacje:

@POST

: oznacza, ĝe metoda reprezentuje ĝÈdanie HTTP

POST

@Consumes

: definiuje przyjmowane przez zasób typy mediów. W omawianym

przykïadzie okreĂlono typ mediów

MediaType.APPLICATION_JSON

, którego wartoĂÊ

application/json

@Produces

: definiuje typy mediów zwracane przez ten zasób. W omawianym

przykïadzie okreĂlono typ mediów

MediaType.APPLICATION_JSON

, którego wartoĂÊ

application/json

@ValidateOnExecution

: okreĂla, dla których metod parametry i wartoĂci zwrotne

majÈ byÊ sprawdzane. Szerzej o adnotacjach

@ValidateOnExecution

@Valid

piszÚ

w rozdziale 3.

Jak widaÊ, zmiana prostego obiektu Javy w usïugÚ REST jest bardzo ïatwa. Teraz obejrzymy
podklasÚ klasy

Application

, która bÚdzie zawieraïa definicje komponentów aplikacji JAX-RS

wïÈcznie z metadanymi.

Poniĝej znajduje siÚ kod ěródïowy przykïadowej podklasy klasy

Application

o nazwie

Coffee-

Application

@ApplicationPath("/")
public class CoffeeApplication extends Application {

@Override
public Set<Class<?>> getClasses() {
Set<Class<?>> classes = new HashSet<Class<?>>();
classes.add(CoffeesResource.class);
return classes;
}

Kup książkę

Poleć książkę

Rozdziaá 1. • Podstawy REST

W podklasie tej zostaïa nadpisana metoda

getClasses()

oraz dodano

CoffesResource

. W pliku

WAR podklasy klasy

Application

mogÈ znajdowaÊ siÚ w katalogach WEB-INF/classes i WEB-

-INF/lib.

Wdraĝanie usïug typu RESTful

NastÚpnym krokiem po utworzeniu zasobu i dodaniu metadanych do podklasy klasy

Applica-

tion

jest utworzenie pliku WAR, który moĝna wdroĝyÊ w kaĝdym kontenerze serwletów.

Kod ěródïowy opisywanych przykïadów znajduje siÚ w plikach do pobrania z serwera FTP.
Dodatkowo moĝna w nich znaleěÊ szczegóïowe instrukcje, jak uruchomiÊ te przykïady.

Testowanie usïug typu RESTful

Teraz moĝemy uĝyÊ funkcjonalnoĂci API klienta JAX-RS 2.0 w celu uzyskania dostÚpu do za-
sobów.

W tym podrozdziale opisane sÈ nastÚpujÈce tematy:

API klienta w JAX-RS 2.0,

uzyskiwanie dostÚpu do zasobów RESTful przy uĝyciu narzÚdzia cURL
lub rozszerzenia przeglÈdarki internetowej o nazwie Postman.

API klienta w JAX-RS 2.0

W JAX-RS 2.0 dodano nowe API klienckie sïuĝÈce do uzyskiwania dostÚpu do zasobów RESTful.
Jego punkt poczÈtkowy to

javax.ws.rs.client.Client

Z tego nowego API moĝna korzystaÊ w nastÚpujÈcy sposób:

Client client = ClientFactory.newClient();
WebTarget target = client.target("http://. . ./coffees/orders");
String response = target.request().get(String.class);

Jak widaÊ w tym przykïadzie, domyĂlny egzemplarz klienta tworzy siÚ przy uĝyciu metody

ClientFactory.newClient()

. Za pomocÈ metody

target()

zostaï utworzony obiekt

WebTarget

Z wykorzystaniem obiektów tego typu przygotowuje siÚ ĝÈdanie przez dodanie metody i pa-
rametrów zapytania.

Zanim nie pojawiïy siÚ nowe API, dostÚp do zasobów REST uzyskiwaïo siÚ w nastÚpujÈcy
sposób:

Kup książkę

Poleć książkę

REST. Najlepsze praktyki i wzorce w jĊzyku Java

URL url = new URL("http://. . ./coffees/orders");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("GET");
conn.setDoInput(true);
conn.setDoOutput(false);
BufferedReader br = new BufferedReader(new InputStreamReader(conn.
getInputStream()));
String line;
while ((line = br.readLine()) != null) {
//...

}

Przykïad ten wyraěnie pokazuje, jak duĝego postÚpu dokonano w API klienckim JAX-RS 2.0
— wyeliminowano koniecznoĂÊ uĝywania klasy

HttpURLConnection

, zamiast której moĝna uĝy-

waÊ API

Client

JeĂli ĝÈdanie jest typu

POST

Client client = ClientBuilder.newClient();
Coffee coffee = new Coffee(...);
WebTarget myResource = client.target("http://foo.com/v1/coffees");
myResource.request(MediaType.APPLICATION_XML) .post(Entity.xml(coffee),
Coffee.class);

metoda

WebTarget.request()

zwraca obiekt

javax.ws.rs.client.InvocationBuilder

, który za

pomocÈ metody

post()

wywoïuje ĝÈdanie HTTP

POST

. Metoda

post()

pobiera jednostkÚ z eg-

zemplarza

Coffee

i okreĂla typ mediów jako

APPLICATION_XML

W kliencie zostaje zarejestrowana implementacja klas

MessageBodyReader

MessageBodyWriter

Szerzej na temat tych klas piszĊ w

rozdziale 2.

W poniĝszej tabeli znajduje siÚ zestawienie opisanych do tej pory najwaĝniejszych klas i adno-
tacji JAX-RS.

Nazwa

Opis

javax.ws.rs.Path

OkreĂla ĂcieĝkÚ URI, dla której zasób serwuje metodÚ.

javax.ws.rs.ApplicationPath

Jest uĝywana przez podklasÚ klasy

Application

jako bazowy URL

wszystkich identyfikatorów URI dostarczanych przez zasoby w aplikacji.

javax.ws.rs.Produces

Definiuje typ mediów, jaki moĝe zostaÊ zwrócony przez dany zasób.

javax.ws.rs.Consumes

Definiuje typ mediów przyjmowany przez zasób.

javax.ws.rs.client.Client

Definiuje punkt wejĂciowy dla ĝÈdañ klienta.

javax.ws.rs.client.WebTarget

Definiuje cel zasobu identyfikowany przez URI.

Kup książkę

Poleć książkę

Rozdziaá 1. • Podstawy REST

Klienty to ciÚĝkie obiekty do obsïugi infrastruktury komunikacyjnej po stronie klienta. Poniewaĝ ich two-
rzenie i usuwanie to doĂÊ czasochïonne operacje, powinno siÚ tworzyÊ jak najmniej tych obiektów. Po-
nadto egzemplarz klienta zawsze trzeba poprawnie zamknÈÊ, aby nie dopuĂciÊ do wycieku zasobów.

Uzyskiwanie dostÚpu do zasobów RESTful

W tym podrozdziale znajduje siÚ opis róĝnych sposobów uzyskiwania dostÚpu do zasobów
REST i testowania ich przez klienty.

cURL

cURL to popularne narzÚdzie wiersza poleceñ do testowania API REST. Za jego pomocÈ uĝyt-
kownik moĝe tworzyÊ ĝÈdania, wysyïaÊ je do API i analizowaÊ otrzymane odpowiedzi. Poniĝej
znajduje siÚ parÚ przykïadowych ĝÈdañ

curl

wykonujÈcych podstawowe czynnoĂci:

¿Èdanie curl

Opis

curl http://api.foo.com/v1/coffees/1

Proste ĝÈdanie

GET

curl -H "foo:bar" http://api.foo.com/v1/coffees

¿Èdanie z dodatkiem nagïówka za pomocÈ
parametru

-H

curl -i http://api.foo.com/v1/coffees/1

¿Èdanie z wyĂwietleniem nagïówków odpowiedzi
HTTP za pomocÈ parametru

-i

curl –X POST -d'{"name":"JanKowalski",
"username":"jkow","phone":"412-344-5644"}
http://api.foo.com/v1/users

¿Èdanie metodÈ

POST

utworzenia nowego

uĝytkownika.

ChoÊ narzÚdzie cURL jest bardzo pomocne, ma wiele opcji, które trzeba zapamiÚtaÊ. Dlate-
go czasami lepszym rozwiÈzaniem jest uĝycie narzÚdzia przeglÈdarkowego, np. Postman albo
Advanced REST client.

Postman

Postman dla przeglÈdarki Chrome to doskonaïe narzÚdzie do testowania i rozwijania API
REST. Zawiera przeglÈdarkÚ danych w formatach JSON i XML oraz umoĝliwia podglÈdanie
ĝÈdañ HTTP 1.1, jak równieĝ ich wielokrotne wysyïanie i zapisywanie na przyszïoĂÊ. Postman
dziaïa w Ărodowisku przeglÈdarki internetowej i umoĝliwia teĝ przeglÈdanie danych cookie.

ZaletÈ narzÚdzia Postman w porównaniu z cURL jest przyjazny interfejs uĝytkownika do wpro-
wadzania parametrów, dziÚki czemu nie trzeba wpisywaÊ caïych poleceñ ani skryptów. Ponadto
program ten obsïuguje róĝnego rodzaju metody uwierzytelniania, takie jak uwierzytelnianie
podstawowe czy przy uĝyciu skrótów (tzw. digest access authentication).

Kup książkę

Poleć książkę

REST. Najlepsze praktyki i wzorce w jĊzyku Java

Poniĝej znajduje siÚ zrzut ekranu przedstawiajÈcy sposób wysyïania zapytañ w narzÚdziu
Postman.

Na powyĝszym zrzucie ekranu przedstawiono okno aplikacji Postman. Najprostszym sposo-

bem na przetestowanie tego programu jest uruchomienie go w przeglÈdarce Chrome.

NastÚpnie naleĝy wybraÊ metodÚ HTTP

GET

i wpisaÊ adres URL

api.postcodes.io/random/

postcodes

. (PostCodes to darmowa otwarta usïuga, której dziaïanie opiera siÚ na danych geo-

graficznych).

Otrzymasz odpowiedě JSON podobnÈ do poniĝszej:

{
"status": 200,
"result": {

"postcode": "OX1 9SN",
"quality": 1,
"eastings": 451316,

"northings": 206104,
"country": "England",
"nhs_ha": "South Central",

"admin_county": "Oxfordshire",
"admin_district": "Oxford",
"admin_ward": "Carfax",
...}

}

Po lewej stronie okna znajdujÈ siÚ róĝne zapytania, które zostaïy dodane do kolekcji, np. po-
branie wszystkich zamówieñ kawy, pobranie jednego konkretnego zamówienia, utworzenie

zamówieñ itd. na podstawie róĝnych przykïadów z tej ksiÈĝki. Moĝesz teĝ tworzyÊ wïasne ko-
lekcje zapytañ.

Kup książkę

Poleć książkę

Rozdziaá 1. • Podstawy REST

Pobieranie przykïadów kodu
Pliki z przykïadowym kodem ěródïowym moĝna pobraÊ z serwera FTP wydawnictwa Helion, pod adresem

ftp://ftp.helion.pl/przyklady/restja.zip

WiÚcej informacji na temat narzÚdzia Postman znajduje siÚ na stronie

http://www.getpostman.com/

Inne narzÚdzia

Oto parÚ innych narzÚdzi, które równieĝ mogÈ byÊ przydatne w pracy z zasobami REST.

Advanced REST client

Advanced REST client to kolejne rozszerzenie przeglÈdarki Chrome oparte na Google Web-
Toolkit i sïuĝÈce do testowania oraz tworzenia API REST.

JSONLint

JSONLint to proste internetowe narzÚdzie do sprawdzania poprawnoĂci danych w formacie
JSON. Gdy wysyïa siÚ dane w tym formacie, dobrze jest sprawdziÊ, czy sÈ sformatowane zgod-

nie ze specyfikacjÈ. Moĝna to zrobiÊ wïaĂnie za pomocÈ narzÚdzia JSONLint. WiÚcej informa-
cji na jego temat znajduje siÚ na stronie http://jsonlint.com/.

Najlepsze praktyki projektowania zasobów

W tym podrozdziale znajduje siÚ opis niektórych najlepszych praktyk projektowania zasobów
RESTful:

Programista API powinien uĝywaÊ rzeczowników, aby uïatwiÊ uĝytkownikowi
poruszanie siÚ po zasobach, a czasowników tylko jako metod HTTP. Na przykïad

URI

/user/1234/books

jest lepszy niĝ

/user/1234/getBook

Do identyfikacji podzasobów uĝywaj asocjacji. Na przykïad aby pobraÊ autorów

ksiÈĝki 5678 dla uĝytkownika 1234, powinno siÚ uĝyÊ URI

/user/1234/books/

5678/authors

Do pobierania specyficznych wariacji uĝywaj parametrów zapytañ. Na przykïad

aby pobraÊ wszystkie ksiÈĝki majÈce 10 recenzji, uĝyj URI

/user/1234/

books?reviews_counts=10

W ramach parametrów zapytañ w razie moĝliwoĂci zezwalaj na czÚĂciowe

odpowiedzi. Przykïadem moĝe byÊ pobranie tylko nazwy i wieku uĝytkownika.

Klient moĝe wysïaÊ w URI parametr zapytania

?fields

zawierajÈcy listÚ pól,

które chce otrzymaÊ od serwera, np.

/users/1234?fields=name,age

Kup książkę

Poleć książkę

REST. Najlepsze praktyki i wzorce w jĊzyku Java

Zdefiniuj domyĂlny format odpowiedzi na wypadek, gdyby klient nie podaï,

jaki format go interesuje. WiÚkszoĂÊ programistów jako domyĂlnego formatu

uĝywa JSON.

W nazwach atrybutów stosuj

notacjÚWielbïÈdziÈ

lub ze znakami podkreĂlenia

Dla kolekcji zapewnij standardowe API liczÈce, np.

users/1234/books/count

aby klient mógï sprawdziÊ, ilu obiektów moĝe siÚ spodziewaÊ w odpowiedzi.
BÚdzie to teĝ pomocne dla klientów uĝywajÈcych stronicowania. Szerzej na temat

stronicowania piszÚ w rozdziale 5.

Zapewnij opcjÚ eleganckiego drukowania —

users/1234?pretty_print

. Ponadto

nie powinno siÚ buforowaÊ zapytañ z parametrem drukowania.

Staraj siÚ minimalizowaÊ komunikacjÚ przez dostarczenie jak najpeïniejszych

informacji w pierwszej odpowiedzi. Chodzi o to, ĝe jeĂli serwer nie dostarczy

wystarczajÈcej iloĂci danych w odpowiedzi, klient bÚdzie musiaï wysïaÊ kolejne

ĝÈdania, aby zdobyÊ potrzebne mu informacje. W ten sposób marnuje siÚ zasoby
i wyczerpuje limit ĝÈdañ klienta. Szerzej na temat ograniczania liczby ĝÈdañ klienta

piszÚ w rozdziale 5.

Zalecana lektura

RFC 2616: http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html.

Model dojrzaïoĂci Richardsona: http://www.crummy.com/writing/speaking/

2008-QCon/act3.html.

Implementacja JAX-RS Jersey: https://jersey.java.net/.

InspectB.in: http://inspectb.in/.

Postman: http://www.getpostman.com/.

Advanced REST Client: https://code.google.com/p/chrome-rest-client/.

Podsumowanie

W tym rozdziale przedstawiïam podstawowe zaïoĝenia technologii REST, opisaïam API CRUD
oraz pokazaïam, jak projektowaÊ zasoby RESTful. W przykïadach uĝyte zostaïy adnotacje JAX-
-RS 2.0, za pomocÈ których moĝna reprezentowaÊ metody HTTP, i API klienckie, przy uĝyciu
których moĝna odnosiÊ siÚ do zasobów. Ponadto zrobiïam przeglÈd najlepszych praktyk pro-
jektowania usïug typu RESTful.

W nastÚpnym rozdziale znajduje siÚ rozszerzenie tych wiadomoĂci. Bardziej szczegóïowo po-
znasz zasady negocjowania treĂci, dostawców jednostek w JAX-RS 2.0, techniki obsïugi bïÚdów,
sposoby kontrolowania wersji oraz kody odpowiedzi REST. Ponadto dowiesz siÚ, w jaki spo-
sób serwer moĝe wysyïaÊ do klienta odpowiedzi przy uĝyciu strumieniowania i kawaïkowania.

Kup książkę

Poleć książkę

Skorowidz

adnotacja

@Asynchronous, 72
@Consumes, 34

@DefaultValue, 90
@Produces, 33

@Suspended, 72
@VerifyValue, 50
@WebFilter, 82

NotNull, 50
Valid, 49

ValidateOnExecution, 49

adnotacje JAX-RS, 26

adres URL, 35
AMQP, Advanced Messaging Queing Protocol, 74

Apache Log4j, 47
API, 23

CRUD, 30

GitHub, 113
Graph portalu Facebook, 114

klienta, 25
reagujÈce na bieĝÈco, 98

REST, 46, 66, 68
REST Facebooka, 69

REST portalu GitHub, 111
REST portalu Twitter, 117

SSE, 102

aplikacje

chmurowe, 107

konsumenckie, 56
macierzyste, 57

sieciowe, 57

architektura mikrousïugowa, 108

niezaleĝnoĂÊ, 109

podziaï funkcjonalnoĂci, 109
prostota, 108
skalowalnoĂÊ, 109
wyodrÚbnienie problemów, 108

architektura REST, 59
asynchroniczne

obsïugiwanie zadañ, 74
przetwarzanie, 70

atrybut

href, 93
method, 94
rel, 94

autoryzacja, 54

Bean Validation, 49
bezpieczeñstwo, 45
bezpieczeñstwo metod, 18
bezstanowoĂÊ, 16
biblioteka Log4j, 47
bïÈd

406, 34
415, 34
420, 87
429, 80, 85

BOSH, 107
buforowanie, 64, 69, 86
buforowanie na serwerze, 70

Kup książkę

Poleć książkę

REST. Najlepsze praktyki i wzorce w jĊzyku Java

122

CRUD, create, read, update, delete, 19
czas

odpowiedzi, 64
ĝycia tokenu, 58

czasowniki, 113
czasowniki HTTP, 17, 21

dane

JSON, 39
osobowe, 48

dodanie metadanych, 25
dokumentowanie usïug, 95
dostawca

toĝsamoĂci, 53
usïug, 53, 56
jednostek, 35

dostÚp do zasobów REST, 25, 27
dyrektywa QoS, 100
dyrektywy nagïówka Cache-Control, 65
dziaïanie gniazd sieciowych, 105

eksplorator API Graph, 115
elementy architektury REST, 59

filtr

ograniczajÈcy ĝÈdania, 82
rejestrujÈcy, 46

format JSON, 39
funkcje interfejsu EventSource, 102
funkcjonalnoĂci gniazd sieciowych, 106

gniazdo sieciowe, WebSocket, 104
grant autoryzacji, 57

HATEOAS, 18, 92, 93

idempotentnoĂÊ metod, 18
identyfikacja

metainformacji, 48
metod, 20
osoby, 48
reprezentacji zasobu, 22

identyfikator URI, 40
identyfikator URI zasobu, 19
implementacja

OAuth, 58
API, 23

informacje o awarii, 47
interfejs

EventSource, 102
ExceptionMapper, 52
Future, 71, 73
MessageBodyReader, 35
MessageBodyWriter, 35

internacjonalizacja, 91
IPN, Instant Payment Notification, 104

JavaScript, 102
JAXB, 39
JAX-RS, 23, 49
Jersey, 38, 58, 103
JSON, 38
JSON Patch, 76

klasa

AccessData, 83
ChunkedInput, 38
ChunkedOutput, 37
CoffeesResource, 49
Filter, 82
JSONArray, 39
JSONParser, 39
LoggingFilter, 47
RateLimiter, 81, 84
ResourceError, 52
ResponseBuilder, 43
StreamingOutput, 36
VariantListBuilder, 34

Kup książkę

Poleć książkę

Skorowidz

123

klasy JAX-RS, 26
klient, 57
kod

200, 68
202, 73
304, 67, 69
406, 34
415, 34
420, 87
429, 80, 85
odpowiedzi, 42, 43, 50

kolejka wiadomoĂci, 74
komunikacja na bieĝÈco, 106

liczba ĝÈdañ, 80
lista wariantów reprezentacji, 34
logowanie pojedyncze, SSO, 53
lokalizacja, 91

maper wyjÈtków, 51
metadane, 24, 91
metoda

build(), 34
doFilter(), 84
getBookInJSON(), 35
getBookInXML(), 35
getSize(), 36
isCancelled(), 71
isDone(), 71
isReadable(), 36
isWriteable(), 36
JSON Patch, 76
prepareResponse(), 73
readFrom(), 36
selectVariant(), 34
writeTo(), 36

metody

HTTP, Patrz ĝÈdanie
idempotentne, 18
uwierzytelniania, 27

mikrousïugi, 107–110
model

dojrzaïoĂci Richardsona, 16
PubSubHubbub, 99

strumieniowania, 100

nagïówek

Accept, 33, 41
Cache-Control, 65, 66
Content-Language, 91

Content-Length, 37
Content-Type, 33

ETag, 65, 68
Expires, 65

Last-Modified, 65
Retry-After, 80, 84

X-RateLimit-Remaining, 81

nagïówki buforowania

silne, 64

sïabe, 64

narzÚdzie

Advanced REST client, 29
cURL, 27

JSONLint, 29
Postman, 27, 29

negocjacja treĂci, 32

poprzez adres URL, 35

poprzez nagïówki HTTP, 32

niezawodnoĂÊ, 16
numer wersji, 41

w nagïówku Accept, 41
w parametrze zapytaniowym, 41

OAuth, Open Authorization, 54

OAuth 1.0, 57
OAuth 2.0, 58

obiekt

cacheControl, 66

Variant, 34

obsïuga

bïÚdów, 51, 113, 116, 119
kodów odpowiedzi, 50

wyjÈtków, 50

odpowiedzi REST, 31
ograniczanie liczby ĝÈdañ, 80–82, 114, 117

okreĂlanie

wersji, 40

wersji API, 41

OpenID Connect, 59

operacje

asynchroniczne, 70

dïugotrwaïe, 70

Kup książkę

Poleć książkę

REST. Najlepsze praktyki i wzorce w jĊzyku Java

124

pliki WAR/EAR, 108
POJO, 39
poprawnoĂÊ usïug REST, 49
portal Facebook, 114

czynnoĂci zasobów, 116
obsïuga bïÚdów, 116
ograniczanie liczby ĝÈdañ, 117
wersjonowanie, 116

portal GitHub, 111

akcje zasobów, 113
obsïuga bïÚdów, 113
ograniczanie liczby ĝÈdañ, 114
pobieranie informacji, 112
wersjonowanie, 113

portal Twitter, 117

dziaïania na zasobach, 118
obsïuga bïÚdów, 119
wersjonowanie, 119

POX, Plain Old XML, 17
procedura

bookavailable, 102
newbookadded, 102

procedury nasïuchowe, 102
proces

asynchronicznego przetwarzania, 71
autoryzacji, 55

projektowanie

wydajnych rozwiÈzañ, 63
zasobów, 29, 31

protokóï

AMQP, 74
ATOM/RSS, 99
OAuth, 55, 56
SAML, 54
WebSocket, 104
XMPP, 106

przetwarzanie

asynchroniczne, 70
danych JSON, 39
niskopoziomowe, 39

PuSH, 99, 104

QoS, Quality of Service, 100

rejestrowanie

informacji, 46, 47
treĂci, 48
ĝÈdañ, 86

REST, Representational State Transfer, 15
RESTEasy, 69
rodzaje

odpowiedzi REST, 31
stronicowania, 88

rola

identity provider, 53
klient, 56
principal, 53
service provider, 53
serwer, 56
uĝytkownik, 56

rozszerzalnoĂÊ, 94

SAML, Security Assertion Markup Language, 53
serializacja zasobów, 35
serwer, 100
skalowalnoĂÊ, 16
SOAP, Simple Object Access Protocol, 15
sondowanie, polling, 98
sondowanie spowolnione, 107
sprawdzanie poprawnoĂci

danych, 29
usïug REST, 49

SSE, Server-Send Events, 100
SSL, 58
SSO, Single Sign-On, 53
staïa REQ_LIMIT, 82
status

COMPLETED, 75
PROCESSING, 75

statyczna negocjacja treĂci, 34
stronicowanie

czasowe, 88
kursorowe, 89
odpowiedzi, 87
offsetowe, 88

struktura ConcurrentHashMap, 83
strumieniowanie, 86
systemy rejestrowania danych, 48
szyfrowanie, 58

Kup książkę

Poleć książkę