REST Najlepsze praktyki i wzorce w jezyku Java

background image
background image

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

Tłumaczenie: Łukasz Piwko

ISBN: 978-83-283-0644-8

Copyright © Packt Publishing 2014.

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

Polish edition copyright © 2015 by Helion S.A.
All rights reserved.

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.

Kup książkę

Poleć książkę

Oceń książkę

Księgarnia internetowa

Lubię to! » Nasza społeczność

background image

Spis treĂci

O autorce

7

PodziÚkowania

8

O recenzentach

9

WstÚp

11

Rozdziaï 1. Podstawy REST

15

Wprowadzenie do REST

16

REST i bezstanowoĂÊ

16

Model dojrzaïoĂci Richardsona

16

Poziom 0 — zdalne wywoïywanie procedur

17

Poziom 1 — zasoby REST

17

Poziom 2 — dodatkowe czasowniki HTTP

17

Poziom 3 — HATEOAS

18

Bezpieczeñstwo i idempotentnoĂÊ

18

Bezpieczeñstwo metod

18

IdempotentnoĂÊ metod

18

Zasady projektowe dotyczÈce budowy usïug typu RESTful

19

Wyznaczenie identyfikatorów URI zasobów

19

Identyfikacja metod obsïugiwanych przez zasób

20

Czasowniki HTTP w REST

21

PUT czy POST

22

Identyfikacja róĝnych reprezentacji zasobu

22

Implementowanie API

23

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

23

Kup książkę

Poleć książkę

background image

REST. Najlepsze praktyki i wzorce w jĊzyku Java

4

Wdraĝanie usïug typu RESTful

25

Testowanie usïug typu RESTful

25

API klienta w JAX-RS 2.0

25

Uzyskiwanie dostÚpu do zasobów RESTful

27

Inne narzÚdzia

29

Najlepsze praktyki projektowania zasobów

29

Zalecana lektura

30

Podsumowanie

30

Rozdziaï 2. Projektowanie zasobów

31

Rodzaje odpowiedzi REST

31

Negocjacja treĂci

32

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

32

Negocjacja treĂci poprzez adres URL

35

Dostawcy jednostek i róĝne reprezentacje

35

StreamingOutput

36

ChunkedOutput

37

Jersey i JSON

38

Wersjonowanie API

40

OkreĂlanie wersji w identyfikatorze URI

40

Numer wersji w parametrze zapytaniowym ĝÈdania

41

OkreĂlanie numeru wersji w nagïówku Accept

41

Kody odpowiedzi i wzorce REST

42

Zalecana lektura

43

Podsumowanie

44

Rozdziaï 3. Bezpieczeñstwo i wykrywalnoĂÊ

45

Rejestrowanie informacji w API REST

46

Najlepsze praktyki rejestrowania informacji w API REST

47

Sprawdzanie poprawnoĂci usïug REST

49

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

zwiÈzanych z weryfikacjÈ poprawnoĂci danych

50

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

51

Uwierzytelnianie i autoryzacja

52

Co to jest uwierzytelnianie

53

Co to jest autoryzacja

54

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

57

Tokeny odĂwieĝania a tokeny dostÚpu

57

Najlepsze praktyki przy implementacji OAuth w API REST

58

OpenID Connect

59

Elementy architektury REST

59

Zalecana lektura

61

Podsumowanie

62

Kup książkę

Poleć książkę

background image

Spis treĞci

5

Rozdziaï 4. Projektowanie wydajnych rozwiÈzañ

63

Zasady buforowania

64

Szczegóïy buforowania

64

Typy nagïówków buforowania

64

Nagïówek Cache-Control i dyrektywy

65

Nagïówek Cache-Control i API REST

66

Znaczniki ETag

67

API REST Facebooka i nagïówki ETag

69

Asynchroniczne i dïugotrwaïe operacje w REST

70

Asynchroniczne przetwarzanie ĝÈdañ i odpowiedzi

70

Najlepsze praktyki pracy z zasobami asynchronicznymi

73

Wysyïanie kodu statusu 202 Accepted

73

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

74

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

74

Metoda HTTP PATCH i czÚĂciowe aktualizacje

74

JSON Patch

76

Zalecana lektura

77

Podsumowanie

77

Rozdziaï 5. Zaawansowane zasady projektowania

79

Techniki ograniczania liczby ĝÈdañ 80

Ukïad projektu

81

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

86

Stronicowanie odpowiedzi

87

Rodzaje stronicowania

88

Ukïad projektu

90

Internacjonalizacja i lokalizacja

91

Róĝne tematy

92

HATEOAS

92

API REST portalu PayPal i HATEOAS

93

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

94

Testowanie usïug typu RESTful

95

Zalecana lektura

96

Podsumowanie

96

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

97

API reagujÈce na bieĝÈco

98

Sondowanie

98

Model PuSH — PubSubHubbub

99

Model strumieniowania

100

Uchwyty sieciowe

103

Gniazda sieciowe

104

Kup książkę

Poleć książkę

background image

REST. Najlepsze praktyki i wzorce w jĊzyku Java

6

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ę

background image

1

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:

Q

Wprowadzenie do technologii REST.

Q

Bezpieczeñstwo i idempotentnoĂÊ.

Q

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

Q

Standardowe API Javy dla usïug typu RESTful.

Q

Najlepsze techniki projektowania usïug typu RESTful.

Kup książkę

Poleć książkę

background image

REST. Najlepsze praktyki i wzorce w jĊzyku Java

16

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:

Q

Wszystkie zasoby okreĂla identyfikator URI.

Q

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

Q

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

Q

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ę

background image

Rozdziaá 1. • Podstawy REST

17

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ę

background image

REST. Najlepsze praktyki i wzorce w jĊzyku Java

18

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ę

background image

Rozdziaá 1. • Podstawy REST

19

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:

Q

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

Q

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).

Q

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

Q

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

Q

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.

Q

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ę

background image

REST. Najlepsze praktyki i wzorce w jĊzyku Java

20

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

i

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ę

background image

Rozdziaá 1. • Podstawy REST

21

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ę

background image

REST. Najlepsze praktyki i wzorce w jĊzyku Java

22

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

i

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ę

background image

Rozdziaá 1. • Podstawy REST

23

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:

Q

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:

Q

narzÚdziami do sprawdzania poprawnoĂci ziaren,

Q

obsïugÈ API klienta,

Q

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:

Q

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

Q

tworzenie nowych zamówieñ,

Q

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ę

background image

REST. Najlepsze praktyki i wzorce w jĊzyku Java

24

2. NastÚpnie definiujemy metodÚ o nazwie

getCoffeeList()

. Ma ona nastÚpujÈce

adnotacje:

Q

@GET

: oznacza, ĝe metoda reprezentuje ĝÈdanie HTTP

GET

.

Q

@PATH

: w tym przypadku ĝÈdania

GET

zasobu

v1/coffees/orders

bÚdÈ

obsïugiwane przez metodÚ

getCoffeeList()

.

Q

@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:

Q

@POST

: oznacza, ĝe metoda reprezentuje ĝÈdanie HTTP

POST

.

Q

@Consumes

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

przykïadzie okreĂlono typ mediów

MediaType.APPLICATION_JSON

, którego wartoĂÊ

to

application/json

.

Q

@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

.

Q

@ValidateOnExecution

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

majÈ byÊ sprawdzane. Szerzej o adnotacjach

@ValidateOnExecution

i

@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ę

background image

Rozdziaá 1. • Podstawy REST

25

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:

Q

API klienta w JAX-RS 2.0,

Q

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ę

background image

REST. Najlepsze praktyki i wzorce w jĊzyku Java

26

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

i

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ę

background image

Rozdziaá 1. • Podstawy REST

27

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ę

background image

REST. Najlepsze praktyki i wzorce w jĊzyku Java

28

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ę

background image

Rozdziaá 1. • Podstawy REST

29

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:

Q

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

.

Q

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

.

Q

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

.

Q

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ę

background image

REST. Najlepsze praktyki i wzorce w jĊzyku Java

30

Q

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.

Q

W nazwach atrybutów stosuj

notacjÚWielbïÈdziÈ

lub ze znakami podkreĂlenia

_

.

Q

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.

Q

Zapewnij opcjÚ eleganckiego drukowania —

users/1234?pretty_print

. Ponadto

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

Q

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

Q

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

Q

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

2008-QCon/act3.html.

Q

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

Q

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

Q

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

Q

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ę

background image

Skorowidz

A

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

B

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ę

background image

REST. Najlepsze praktyki i wzorce w jĊzyku Java

122

C

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

odpowiedzi, 64
ĝycia tokenu, 58

czasowniki, 113
czasowniki HTTP, 17, 21

D

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

E

eksplorator API Graph, 115
elementy architektury REST, 59

F

filtr

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

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

G

gniazdo sieciowe, WebSocket, 104
grant autoryzacji, 57

H

HATEOAS, 18, 92, 93

I

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

J

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

K

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ę

background image

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

L

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

M

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

N

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

O

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ę

background image

REST. Najlepsze praktyki i wzorce w jĊzyku Java

124

P

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

Q

QoS, Quality of Service, 100

R

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

S

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ę

background image

Skorowidz

125

T

tablica JSONArray, 90
technologia

BOSH, 107
OpenID Connect, 59
REST, 11, 97
SOA, 15

termin wygaĂniÚcia, 74
testowanie

usïug, 95
typu RESTful, 25

token, 54

dostÚpu, 57
odĂwieĝania, 57, 58

tworzenie

API REST, 29
asynchronicznego zasobu, 72
listy wariantów reprezentacji, 34
zasobu RESTful, 23

typ MIME, 34
typy

nagïówków buforowania, 64
znaczników ETag, 68

U

uchwyt sieciowy, WebHook, 103
ukïad projektu, 81, 90
unikanie sondowania, 86
usïuga

GitHub, 104
IPN, 104

usïugi typu RESTful, 19
utrata poïÈczenia, 101
uwierzytelnianie, 27, 53
uzgodnienie, handshake, 107
uĝycie gniazd sieciowych, 106

W

wdraĝanie usïug typu RESTful, 25
wersjonowanie API, 40
weryfikacja poprawnoĂci danych, 50
wÚzeï komunikacyjny, 99
wiadomoĂÊ

SSE, 101
SSE z identyfikatorem, 101

wiÈzanie

identyfikatora ze zdarzeniem, 101
nazw ze zdarzeniami, 101

widocznoĂÊ, 16
WSDL, Web Service Description Language, 15
wyjÈtek, 50

CoffeeNotFoundException, 51

wykrywalnoĂÊ, 45
wysyïanie

nagïówka Accept, 42
numeru wersji, 41

wzorce REST, 42

X

XMPP, 106

Z

zaciemnianie danych poufnych, 47
zasady

buforowania, 64
projektowania, 79

zasoby

asynchroniczne, 73
REST, 17
RESTful, 19, 22

zdalne wywoïywanie procedur, 17
zdarzenia

SSE, 100–103, 107
uchwytów sieciowych, 103

ziarno JAXB, 39
znaczniki ETag, 67, 68

¿

ĝÈdania

curl, 27, 85
w pÚtlach, 86

ĝÈdanie

DELETE, 21
GET, 21
HEAD, 22
OAuth, 55
PATCH, 74, 76
POST, 21, 26
PUT, 21
Upgrade, 104

Kup książkę

Poleć książkę

background image

REST. Najlepsze praktyki i wzorce w jĊzyku Java

126

Kup książkę

Poleć książkę

background image
background image

Wyszukiwarka

Podobne podstrony:
REST Najlepsze praktyki i wzorce w jezyku Java restja
REST Najlepsze praktyki i wzorce w jezyku Java
Zwinne wytwarzanie oprogramowania Najlepsze zasady wzorce i praktyki 2
Zwinne wytwarzanie oprogramowania Najlepsze zasady wzorce i praktyki
Inzynieria oprogramowania w ujeciu obiektowym UML wzorce projektowe i Java iowuje
Programowanie współbieżne i rozproszone w języku Java stpiczynski
09 Obsługa baz danych w języku Java
Najlepsze praktyki upadłości konsumenckiej
OMÓWIENIE INTERFEJSÓW I KLAS ABSTRAKCYJNYCH W JĘZYKU JAVA
Efektywne Programowanie W Języku Java

więcej podobnych podstron