REST - najlepsze praktyki i wzorece dla Java

7/23/2019 REST - najlepsze praktyki i wzorece dla Java

http://slidepdf.com/reader/full/rest-najlepsze-praktyki-i-wzorece-dla-java 1/30



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 informacjizawartych w książce.

Wydawnictwo HELION

ul. Kościuszki 1c, 44-100 GLIWICE

tel. 32 231 22 19, 32 230 98 63

e-mail: [email protected]

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/restjaMoż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ść

http://helion.pl/rt/restja


http://helion.pl/rf/restja


http://helion.pl/ro/restja


http://helion.pl/

http://helion.pl/

http://ebookpoint.pl/r/4CAKF



http://helion.pl/






Spis treci

O autorce 7

Podzikowania 8

O recenzentach 9

Wstp 11

Rozdzia 1. Podstawy REST 15

Wprowadzenie do REST 16

REST i bezstanowo 16

Model dojrzaoci Richardsona 16

Poziom 0 — zdalne wywoywanie procedur 17

Poziom 1 — zasoby REST 17

Poziom 2 — dodatkowe czasowniki HTTP 17

Poziom 3 — HATEOAS 18

Bezpieczestwo i idempotentno 18

Bezpieczestwo metod 18Idempotentno metod 18

Zasady projektowe dotyczce budowy usug typu RESTful 19

Wyznaczenie identyfikatorów URI zasobów 19

Identyfikacja metod obsugiwanych 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 usug RESTful (JAX-RS) 23

Kup książkę Poleć książkę







REST. Najlepsze praktyki i wzorce w jzyku Java

4

Wdraanie usug typu RESTful 25

Testowanie usug typu RESTful 25

API klienta w JAX-RS 2.0 25

Uzyskiwanie dostpu do zasobów RESTful 27

Inne narzdzia 29

Najlepsze praktyki projektowania zasobów 29Zalecana lektura 30

Podsumowanie 30

Rozdzia 2. Projektowanie zasobów 31

Rodzaje odpowiedzi REST 31

Negocjacja treci 32

Negocjacja treci przy uyciu nagówków HTTP 32

Negocjacja treci poprzez adres URL 35

Dostawcy jednostek i róne reprezentacje 35

StreamingOutput 36ChunkedOutput 37

Jersey i JSON 38

Wersjonowanie API 40

Okrelanie wersji w identyfikatorze URI 40

Numer wersji w parametrze zapytaniowym dania 41

Okrelanie numeru wersji w nagówku Accept 41

Kody odpowiedzi i wzorce REST 42

Zalecana lektura 43

Podsumowanie 44

Rozdzia 3. Bezpieczestwo i wykrywalno 45Rejestrowanie informacji w API REST 46

Najlepsze praktyki rejestrowania informacji w API REST 47

Sprawdzanie poprawnoci usug REST 49

Obsuga wyjtków i kodów odpowiedzizwizanych z weryfikacj poprawnoci danych 50

Obsuga bdów w usugach typu RESTful 51

Uwierzytelnianie i autoryzacja 52

Co to jest uwierzytelnianie 53

Co to jest autoryzacja 54

Rónice midzy OAuth 2.0 i OAuth 1.0 57Tokeny odwieania a tokeny dostpu 57

Najlepsze praktyki przy implementacji OAuth w API REST 58

OpenID Connect 59

Elementy architektury REST 59

Zalecana lektura 61

Podsumowanie 62








Spis treci

5

Rozdzia 4. Projektowanie wydajnych rozwiza 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 dugotrwae operacje w REST 70

Asynchroniczne przetwarzanie da i odpowiedzi 70

Najlepsze praktyki pracy z zasobami asynchronicznymi 73

Wysyanie kodu statusu 202 Accepted 73

Ustawianie terminu wyganicia dla obiektów w kolejce 74

Asynchroniczne obsugiwanie zada przy uyciu kolejek wiadomoci 74

Metoda HTTP PATCH i czciowe aktualizacje 74

JSON Patch 76Zalecana 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 pozwalajce 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 93REST i rozszerzalno 94

Inne tematy zwizane z API REST 94

Testowanie usug typu RESTful 95

Zalecana lektura 96

Podsumowanie 96

Rozdzia 6. Nowe standardy i przyszo technologii REST 97

API reagujce na bieco 98

Sondowanie 98

Model PuSH — PubSubHubbub 99

Model strumieniowania 100

Uchwyty sieciowe 103

Gniazda sieciowe 104









6

Inne API i technologie do komunikacji na bieco 106

XMPP 106

BOSH poprzez XMPP 107

Porównanie uchwytów sieciowych, gniazd sieciowych i zdarzewysyanych przez serwer 107

REST i mikrousugi 108Prostota 108

Wyodrbnienie problemów 108Skalowalno 109

Wyrany podzia funkcjonalnoci 109

Niezaleno od jzyka programowania 109

Zalecana lektura 109

Podsumowanie 110

Dodatek A 111

Przegld API REST portalu GitHub 111Pobieranie informacji z portalu GitHub 112

Czasowniki i akcje zasobów 113

Wersjonowanie 113

Obsuga bdów 113

Ograniczanie liczby da 114

Przegld API Graph portalu Facebook 114

Czasowniki i czynnoci zasobów 116

Wersjonowanie 116

Obsuga bdów 116

Ograniczanie liczby da 117

Przegld API portalu Twitter 117Czasowniki i dziaania na zasobach 118

Wersjonowanie 119

Obsuga bdów 119

Zalecana lektura 119

Podsumowanie 119

Skorowidz 121








1

Podstawy REST

Usugi sieciowe w tradycyjnej technologii SOA, umoliwiaj ce zrónicowan komunikacjmidzy aplikacjami, istniej ju od pewnego czasu. Jednym ze sposobów obsugi tej komuni-kacji jest uycie technologii Simple Object Access Protocol (SOAP) i Web Service Description Language (WSDL). S to standardy oparte na formacie XML doskonale sprawdzaj ce si, gdymidzy usugami jest cisy kontakt. Ale nasta a era usug rozproszonych. Teraz róne klientyz internetu, urz dzenia przenone, jak równie inne usugi (wewntrzne i zewntrzne) mog uywa interfejsów API udostpnianych przez rónych dostawców i róne platformy open source. To sprawia, e potrzebne s technologie atwej wymiany informacji midzy usugamirozproszonymi w rónych miejscach, z przewidywalnymi, solidnymi, cile zdefiniowanymi

interfejsami.

Protokó HTTP 1.1, zdefiniowany w dokumencie RFC 2616, jest powszechnie uywany w roz-proszonych systemach hipermedialnych. Technologia Representational State Transfer (REST)bazuje na HTTP i moe by uywana wszdzie tam, gdzie ten protokó. W tym rozdziale przed-stawione s podstawowe wiadomoci na temat projektowania usug typu RESTful oraz uywa-nia takich usug za pomoc standardowych interfejsów API Javy.

W rozdziale omówiono nastpuj ce zagadnienia:

Wprowadzenie do technologii REST.

Bezpieczestwo i idempotentno. Zasady projektowe dotycz ce budowy usug typu RESTful.

Standardowe API Javy dla usug typu RESTful.

Najlepsze techniki projektowania usug typu RESTful.









16

Wprowadzenie do RESTREST to styl architektoniczny zgodny z takimi standardami sieciowymi jak czasowniki HTTPi identyfikatory URI. Obowi zuj w nim nastpuj ce zasady:

Wszystkie zasoby okrela identyfikator URI.

Ka dy zasób moe mie liczne reprezentacje.

Ka dy zasób mona pobra , zmodyfikowa , utworzy i usun standardowymimetodami HTTP.

Na serwerze nie s przechowywane adne informacje o stanie.

REST i bezstanowoW REST obowi zuje zasada bezstanowoci. Ka de danie przesyane przez klienta do ser-wera musi zawiera wszystkie informacje potrzebne do obsugi 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 dziki wyeliminowaniu punktów kontrol-nych i wznowienia w przypadku czciowych niepowodze operacji. Poprawa skalowalno ci

jest efektem zwikszenia liczby da , które jest w stanie przetworzy serwer, co jest moliwedziki 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. Wicej informacji na ten temat mona znale pod adresem http://www.ics.

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

To s podstawowe wiadomoci o technologii REST. Teraz zajmiemy si rónymi poziomamidojrza oci i zobaczymy, gdzie poród nich mieci si ta technologia.

Model dojrzaoci RichardsonaModel dojrzaoci Richardsona to opracowany przez Leonarda Richardsona model opisuj -cy podstawy REST pod wzgldem zasobów, czasowników i hipermediów. Punktem pocz t-kowym tego modelu jest wykorzystanie HTTP jako warstwy transportowej. Ukazuje to poni-szy schemat.








Rozdzia 1. • Podstawy REST

17

Poziom 0 — zdalne wywoywanie procedurDo poziomu 0 zalicza si przesyanie danych przy uyciu technologii SOAP i XML-RPC jakoPOX (ang. Plain Old XML — zwyky XML). Uywana jest tylko metoda POST. Jest to najprost-

szy sposób budowania aplikacji SOA z jedn metod POST i przy uyciu formatu XML do ko-

munikacji midzy usugami.

Poziom 1 — zasoby RESTNa poziomie 1 uywane s metody POST, a zamiast funkcji i przekazywania argumentów wy-korzystuje si identyfikatory URI REST. Zatem nadal uywana jest tylko jedna metoda HTTP.Zalet tego poziomu w stosunku do zerowego jest podzia zoonej funkcjonalnoci na kilka zasobów za pomoc jednej metody POST su cej do komunikacji midzy usugami.

Poziom 2 — dodatkowe czasowniki HTTPNa poziomie drugim jest wicej czasowników, np. GET, HEAD, DELETE, PUT i oczywicie POST.

Poziom ten reprezentuje rzeczywisty przypadek uycia technologii REST, w której wykorzy-stuje si róne czasowniki HTTP do wykonywania rónych da , a system moe zawiera wiele zasobów.









18

Poziom 3 — HATEOASHATEOAS (ang. Hypermedia as the Engine of Application State — hipermedia jako mecha-nizm obsugi stanu aplikacji) reprezentuje najwyszy stopie dojrza oci w modelu Richard-

sona. Odpowiedzi na dania klientów zawieraj elementy hipermedialne, przy uyciu którychklient moe zdecydowa , co robi dalej. Zasady te uatwiaj wykrywanie usug i sprawiaj , eodpowiedzi s bardziej zrozumia e. Tocz si dyskusje na temat tego, czy HATEOAS rzeczy-wicie spenia wymagania RESTful, poniewa reprezentacja zawiera o wiele wicej informa-cji ni tylko opis zasobu. W rozdziale 5. przedstawiam par przykadów pokazuj cych, jak za-implementowano HATEOAS jako cz API niektórych platform, np. PayPal.

W nastpnym podrozdziale wyja niam pojcia bezpieczestwo i idempotentno, które s bar-dzo wa ne w usugach RESTful.

Bezpieczestwo i idempotentnoW poniszych dwóch podrozdzia ach dokadniej wyja niam znaczenie bezpieczestwa i idem-potentnoci metod.

Bezpieczestwo metodBezpieczna metoda to taka, która nie zmienia stanu na serwerze. Warunek ten spenia na przy-

kad metoda GET /v1/coffees/orders/1234.

Bezpieczne metody, do których zaliczaj si GET i HEAD, mona 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 metodMetoda idempotentna to taka, która zwraca taki sam wynik niezalenie od tego, ile razy zosta-nie wywoana.

Metoda GET jest idempotentna, poniewa niezalenie od tego, ile razy si j wywoa, zawsze zwraca

tak sam odpowied.

Metoda PUT te jest idempotentna, poniewa wielokrotne jej wywoanie powoduje aktualizacj tego

samego zasobu i nie zmienia to wyniku.









19

Metoda POST nie jest idempotentna, poniewa jej wielokrotne wywoanie moe dawa róne skutki

i powodowa powstanie wielu zasobów. Metoda DELETE jest idempotentna, gdy usunity zasób znika

i powtórne wywoanie tej samej metody niczego nie zmieni.

Zasady projektowe dotyczce budowy usug typu RESTful

Poniej w punktach przedstawiam proces projektowania, tworzenia i testowania usug typuRESTful. Dalej znajduje si dokadniejszy opis ka dego z tych etapów:

Wyznaczenie identyfikatorów URI zasobów.

Polega na wybraniu rzeczowników do reprezentowania zasobu. Identyfikacja metod obsugiwanych przez zasób.

Polega na wybraniu metod HTTP do wykonywania operacji CRUD (ang. create, read, update, delete — utworzenie, odczytanie, aktualizacja, usunicie).

Identyfikacja rónych reprezentacji zasobu.

Polega na wybraniu, czy zasób bdzie reprezentowany w formacie JSON, XML,HTML, czy tekstowym.

Implementacja usug RESTful przy uyciu API JAX-RS.

Interfejs API naley zaimplementowa na podstawie specyfikacji JAX-RS. Wdroenie usug RESTful.

Wdroenie usugi w kontenerze aplikacji, np. Tomcat, GlassFish lub WildFly.Na przykadach pokazuj, jak tworzy si pliki WAR, i prezentuj sposób wdroenia na serwerze GlassFish 4.0. Poza tym przedstawiony przykad dzia a w ka dymkontenerze zgodnym z Java EE 7.

Testowanie usug RESTful.

Polega na napisaniu API klienta do testowania usug lub uyciu narzdzi cURLalbo przegl darkowych do testowania da REST.

Wyznaczenie identyfikatorów URI zasobówZasoby RESTful s identyfikowane przez identyfikatory URI. Dziki temu technologia REST jest rozszerzalna.

Ponisza tabela zawiera przykady identyfikatorów URI, które mog reprezentowa róne za-soby w systemie.









20

URI Opis

/v1/library/books Moliwa reprezentacja kolekcji zasobów ksikowych w bibliotece.

/v1/library/books/isbn/12345678 Moliwa reprezentacja jednej ksiki identyfikowanej przez numer

ISBN 123456.

/v1/coffees Moliwa reprezentacja wszystkich kaw sprzedanych w kawiarni.

/v1/coffees/orders Moliwa reprezentacja wszystkich zamówionych kaw w kawiarni.

/v1/coffees/orders/123 Moliwa reprezentacja pojedynczego zamówienia kawy

o identyfikatorze 123.

/v1/users/1235 Moliwa reprezentacja uytkownika o identyfikatorze w systemie 1235.

/v1/users/5034/books Moliwa reprezentacja wszystkich ksiek uytkownika

o identyfikatorze 5034.

Wszystkie przedstawione identyfikatory s zbudowane wg jasnego wzorca, który klient moebez trudu zinterpretowa . Wszystkie te zasoby mog mie liczne reprezentacje, np. w forma-cie JSON, XML, HTML lub tekstowym, i mona nimi zarz dza za pomoc metod GET, PUT,POST i DELETE.

Identyfikacja metod obsugiwanych przez zasóbCzasowniki HTTP stanowi wa ny skadnik jednolitego ograniczenia interfejsu, które definiuje zwi zek midzy czynnociami opisywanymi przez dany czasownik w stosunku do opisanegoza pomoc rzeczowników zasobu REST.

Ponisza tabela zawiera zestawienie metod HTTP i opis powodowanych przez nie zdarze orazprosty przykad kolekcji ksiek w bibliotece.

Metoda HTTP URI zasobu Opis

GET /library/books Pobiera list ksiek.

GET /library/books/isbn/12345678 Pobiera ksik o numerze ISBN 12345678.

POST /library/books Tworzy nowe zamówienie ksiki.

DELETE /library/books/isbn/12345678 Usuwa ksik o numerze ISBN 12345678.

PUT /library/books/isbn/12345678 Aktualizuje ksik o numerze ISBN 12345678.

PATCH /library/books/isbn/12345678 Czciowo aktualizuje ksik o numerze ISBN 12345678.

W kolejnym podrozdziale znajduje si opis zastosowania ka dego z czasowników HTTP w kon-tekcie REST.









21

Czasowniki HTTP w RESTCzasowniki HTTP stanowi dla serwera informacj o tym, co ma zrobi z otrzymanymi danymi.

GETGET to najprostsza metoda HTTP pozwalaj ca uzyska dostp do zasobu. Gdy klient kliknieadres URL w przegl darce internetowej, aplikacja ta wysya danie GET pod ten wa nie ad-res. Metoda GET jest bezpieczna i idempotentna. dania wysyane t metod s buforowanei mog zawiera parametry.

Poniej znajduje si proste danie GET pobieraj ce wszystkich aktywnych uytkowników:

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

POSTMetoda POST suy do tworzenia zasobów. dania wysyane przy uyciu tej metody nie s idempotentne ani bezpieczne. Wielokrotne wywoania mog spowodowa utworzenie wieluzasobów.

danie POST powinno powodowa uniewa nienie odpowiedniego elementu w buforze, jelitaki istnieje. W daniach POST nie zaleca si stosowania parametrów zapytaniowych.

Poniej znajduje si danie utworzenia uytkownika:

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

PUT

Metoda PUT suy 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, jeli taka istnieje.

Poniej znajduje si przykad dania PUT aktualizuj cego uytkownika:

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

DELETE

Metoda DELETE suy do usuwania zasobów. Jest idempotentna, ale nie jest bezpieczna. Idem-potentno wynika z tego, e zgodnie ze specyfikacj RFC 2616 skutki uboczne dowolnej wik-szej od zera liczby da s takie same jak jednego dania. Oznacza to, e po usuniciu zaso-bu kolejne wywoania metody DELETE nic nie zmieniaj .









22

Poniej znajduje si przykadowe danie usuwaj ce uytkownika:

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

HEAD

dania typu HEAD s podobne do GET. Rónica midzy nimi polega na tym, e w odpowiedzina danie HEAD zwracane s tylko nagówki HTTP, bez treci. Metoda HEAD jest idempotentna i bezpieczna.

Poniej znajduje si przykadowe danie HEAD wysyane za pomoc narzdzia cURL:

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

Jeli zasób jest duy, to za pomoc dania HEAD mona sprawdzi, czy co si w nim zmienio, zanim si je pobierze przy uyciu dania GET.

PUT czy POSTZgodnie z dokumentem RFC rónica midzy metodami PUT i POST dotyczy identyfikatora URI dania. W metodzie POST przesany identyfikator URI definiuje jednostk, która ma obsuy 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, jeli taki istnieje. Jeli nie ma takiego zasobu, zostanie utworzone nowe za-mówienie, do którego identyfikacji zostanie uyty URI orders/1234.

Zarówno metody PUT, jak i POST mona uywa do tworzenia i aktualizacji zasobów. Wybór jednej z nich

zaley gównie od tego, czy potrzebna jest idempotentno metody, oraz od lokalizacji zasobu.

W nastpnym podrozdziale dowiesz si, jak identyfikowa róne reprezentacje zasobu.

Identyfikacja rónych reprezentacji zasobuZasoby RESTful s jednostkami abstrakcyjnymi, które przed przesaniem do klienta trzeba pod-da serializacji do jakiego reprezentacyjnego formatu. Wród najczciej uywanych repre-zentacji mona wymieni XML, JSON, HTML i zwyky tekst. Zasób moe dostarcza kliento-wi reprezentacj w zalenoci od tego, co klient ten jest w stanie przyj. Klient moe okrelipreferowane przez siebie jzyki i typy mediów. Nazywa si to negocjacj treci i zosta o szcze-góowo opisane w rozdziale 2.









23

Implementowanie APIWiesz ju mniej wicej, jak projektowa zasoby RESTful i jakich czasowników HTTP uywa do wykonywania rónych dzia a na tych zasobach, wic moemy przej do kwestii imple-

mentowania API i budowania usugi typu RESTful. Gównym tematem tego podrozdzia u jest: API Javy dla usug RESTful (JAX-RS).

API Javy dla usug RESTful (JAX-RS) API Javy dla usug RESTful suy do budowania i rozwijania aplikacji wg zasad technologiiREST. Przy uyciu JAX-RS mona udostpnia obiekty Javy jako usugi sieciowe typu RESTful,które s niezalene od podstawowej technologii i uywaj prostego API opartego na adnotacjach.

Najnowsza wersja specyfikacji to JAX-RS 2.0. Od wersji JAX-RS 1.0 róni si przede wszystkim: narzdziami do sprawdzania poprawnoci ziaren,

obsug API klienta,

moliwoci wykonywania wywoa asynchronicznych.

Implementacja specyfikacji JAX-RS nazywa si Jersey.

Wszystkie wymienione tematy zosta y szczegóowo opisane w kolejnych rozdzia ach. Przed-stawiam prosty przykad kawiarni, w którym mona utworzy zasób REST o nazwie Coffees-

Resource o nastpuj cych umiejtnociach:

podanie szczegóów zoonych zamówie,

tworzenie nowych zamówie,

sprawdzenie informacji o wybranym zamówieniu.

Tworzenie zasobu RESTful zaczniemy od utworzenia obiektu Javy o nazwie CoffeesResource.Poniej znajduje si przykad zasobu JAX-RS:

@Path("v1/coffees")

public class CoffeesResource {

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

}

1. W powyszym kodzie zosta utworzony niewielki obiekt Javy o nazwieCoffeesResource. Klas t opatrzyam adnotacj @Path("v1/coffees") okrelaj c ciek URI, dla której klasa ta obsuguje dania.









24

2. Nastpnie definiujemy metod o nazwie getCoffeeList(). Ma ona nastpuj ceadnotacje:

@GET: oznacza, e metoda reprezentuje danie HTTP GET.

@PATH: w tym przypadku dania GET zasobu v1/coffees/orders bd

obsugiwane przez metod getCoffeeList(). @Produces: definiuje typy mediów zwracane przez ten zasób. W omawianym

przykadzie okrelono typ mediów MediaType.APPLICATION_JSON, któregowarto to application/json.

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

@POST@Consumes(MediaType.APPLICATION_JSON)@Produces(MediaType.APPLICATION_JSON)@ValidateOnExecutionpublic Response addCoffee(@Valid Coffee coffee) {

// implementacja}

Jest to metoda o nazwie addCoffee() zawieraj ca nastpuj ce adnotacje:

@POST: oznacza, e metoda reprezentuje danie HTTP POST.

@Consumes: definiuje przyjmowane przez zasób typy mediów. W omawianymprzykadzie okrelono typ mediów MediaType.APPLICATION_JSON, którego wartoto application/json.

@Produces: definiuje typy mediów zwracane przez ten zasób. W omawianymprzykadzie okrelono typ mediów MediaType.APPLICATION_JSON, którego wartoto application/json.

@ValidateOnExecution: okrela, dla których metod parametry i wartoci zwrotnemaj by sprawdzane. Szerzej o adnotacjach @ValidateOnExecution i @Valid piszw rozdziale 3.

Jak wida , zmiana prostego obiektu Javy w usug REST jest bardzo atwa. Teraz obejrzymypodklas klasy Application, która bdzie zawiera a definicje komponentów aplikacji JAX-RSw cznie z metadanymi.

Poniej znajduje si kod ródowy przykadowej 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; }









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.

Wdraanie usug typu RESTfulNastpnym krokiem po utworzeniu zasobu i dodaniu metadanych do podklasy klasy Applica-

tion jest utworzenie pliku WAR, który mona wdroy w ka dym kontenerze serwletów.

Kod ródowy opisywanych przykadów znajduje si w plikach do pobrania z serwera FTP.Dodatkowo mona w nich znale szczegóowe instrukcje, jak uruchomi te przykady.

Testowanie usug typu RESTfulTeraz moemy uy funkcjonalnoci API klienta JAX-RS 2.0 w celu uzyskania dostpu do za-sobów.

W tym podrozdziale opisane s nastpuj ce tematy:

API klienta w JAX-RS 2.0,

uzyskiwanie dostpu do zasobów RESTful przy uyciu narzdzia cURL

lub rozszerzenia przegl darki internetowej o nazwie Postman.

API klienta w JAX-RS 2.0W JAX-RS 2.0 dodano nowe API klienckie su ce do uzyskiwania dostpu do zasobów RESTful. Jego punkt pocz tkowy to javax.ws.rs.client.Client.

Z tego nowego API mona korzysta w nastpuj 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 przykadzie, domylny egzemplarz klienta tworzy si przy uyciu metodyClientFactory.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 pojawiy si nowe API, dostp do zasobów REST uzyskiwa o si w nastpuj cysposób:









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

}

Przykad ten wyra nie pokazuje, jak duego postpu dokonano w API klienckim JAX-RS 2.0— wyeliminowano konieczno uywania klasy HttpURLConnection, zamiast której mona uy-

wa API Client.

Jeli 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()wywouje danie HTTP POST. Metoda post() pobiera jednostk z eg-

zemplarza Coffee i okrela 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 poniszej tabeli znajduje si zestawienie opisanych do tej pory najwa niejszych klas i adno-tacji JAX-RS.

Nazwa Opis

javax.ws.rs.Path Okrela ciek URI, dla której zasób serwuje metod.

javax.ws.rs.ApplicationPath Jest uywana przez podklas klasy Application jako bazowy URLwszystkich identyfikatorów URI dostarczanych przez zasoby w aplikacji.

javax.ws.rs.Produces Definiuje typ mediów, jaki moe 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 wejciowy dla da klienta.

javax.ws.rs.client.WebTarget Definiuje cel zasobu identyfikowany przez URI.









27

Klienty to cikie obiekty do obsugi infrastruktury komunikacyjnej po stronie klienta. Poniewa ich two-

rzenie i usuwanie to do czasochonne operacje, powinno si tworzy jak najmniej tych obiektów. Po-

nadto egzemplarz klienta zawsze trzeba poprawnie zamkn, aby nie dopuci do wycieku zasobów.

Uzyskiwanie dostpu do zasobów RESTfulW tym podrozdziale znajduje si opis rónych sposobów uzyskiwania dostpu do zasobówREST i testowania ich przez klienty.

cURL

cURL to popularne narzdzie wiersza polece do testowania API REST. Za jego pomoc uyt-kownik moe tworzy dania, wysya je do API i analizowa otrzymane odpowiedzi. Poniej

znajduje si par przykadowych da curl wykonuj cych podstawowe czynnoci:

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 pomocparametru -H.

curl -i http://api.foo.com/v1/coffees/1 danie z wywietleniem 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 nowegouytkownika.

Cho narzdzie cURL jest bardzo pomocne, ma wiele opcji, które trzeba zapamita . Dlate-go czasami lepszym rozwi zaniem jest uycie narzdzia przegl darkowego, np. Postman albo Advanced REST client.

Postman

Postman dla przegl darki Chrome to doskona e narzdzie do testowania i rozwijania APIREST. Zawiera przegl dark danych w formatach JSON i XML oraz umoliwia podgl danie

da HTTP 1.1, jak równie ich wielokrotne wysyanie i zapisywanie na przyszo. Postmandzia a w rodowisku przegl darki internetowej i umoliwia te przegl danie danych cookie.

Zalet narzdzia Postman w porównaniu z cURL jest przyjazny interfejs uytkownika do wpro-wadzania parametrów, dziki czemu nie trzeba wpisywa ca ych polece ani skryptów. Ponadtoprogram ten obsuguje rónego rodzaju metody uwierzytelniania, takie jak uwierzytelnianiepodstawowe czy przy uyciu skrótów (tzw. digest access authentication).









28

Poniej znajduje si zrzut ekranu przedstawiaj cy sposób wysyania zapyta w narzdziuPostman.

Na powyszym zrzucie ekranu przedstawiono okno aplikacji Postman. Najprostszym sposo-bem na przetestowanie tego programu jest uruchomienie go w przegl darce Chrome.

Nastpnie naley wybra metod HTTP GET i wpisa adres URL api.postcodes.io/random/

postcodes. (PostCodes to darmowa otwarta usuga, której dzia anie opiera si na danych geo-graficznych).

Otrzymasz odpowied JSON podobn do poniszej:

{ "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, utworzeniezamówie itd. na podstawie rónych przykadów z tej ksiki. Moesz te tworzy wasne ko-lekcje zapyta .









29

Pobieranie przyk adów kodu

Pliki z przyk adowym kodem ródowym mona pobra z serwera FTP wydawnictwa Helion, pod adresem

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

Wicej informacji na temat narzdzia Postman znajduje si na stronie http://www.getpostman.com/ .

Inne narzdziaOto par innych narzdzi, 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 su ce do testowania oraz tworzenia API REST.

JSONLint

JSONLint to proste internetowe narzdzie do sprawdzania poprawnoci danych w formacie JSON. Gdy wysya si dane w tym formacie, dobrze jest sprawdzi, czy s sformatowane zgod-nie ze specyfikacj . Mona to zrobi wa nie za pomoc narzdzia JSONLint. Wicej informa-cji na jego temat znajduje si na stronie http://jsonlint.com/ .

Najlepsze praktyki projektowania zasobówW tym podrozdziale znajduje si opis niektórych najlepszych praktyk projektowania zasobówRESTful:

Programista API powinien uywa rzeczowników, aby uatwi uytkownikowiporuszanie si po zasobach, a czasowników tylko jako metod HTTP. Na przykadURI /user/1234/books jest lepszy ni /user/1234/getBook.

Do identyfikacji podzasobów uywaj asocjacji. Na przykad aby pobra autorów

ksiki 5678 dla uytkownika 1234, powinno si uy URI /user/1234/books/5678/authors.

Do pobierania specyficznych wariacji uywaj parametrów zapyta . Na przykadaby pobra wszystkie ksiki maj ce 10 recenzji, uyj URI /user/1234/

books?reviews_counts=10.

W ramach parametrów zapyta w razie moliwoci zezwalaj na czcioweodpowiedzi. Przykadem moe by pobranie tylko nazwy i wieku uytkownika.Klient moe wysa w URI parametr zapytania ?fields zawieraj cy list pól,które chce otrzyma od serwera, np. /users/1234?fields=name,age.









30

Zdefiniuj domylny format odpowiedzi na wypadek, gdyby klient nie poda , jaki format go interesuje. Wikszo programistów jako domylnego formatuuywa JSON.

W nazwach atrybutów stosuj notacjWielbdzi lub ze znakami podkrelenia _.

Dla kolekcji zapewnij standardowe API licz ce, np. users/1234/books/count,aby klient móg sprawdzi, ilu obiektów moe si spodziewa w odpowiedzi.

Bdzie to te pomocne dla klientów uywaj cych stronicowania. Szerzej na tematstronicowania pisz w rozdziale 5.

Zapewnij opcj eleganckiego drukowania — users/1234?pretty_print. Ponadtonie powinno si buforowa zapyta z parametrem drukowania.

Staraj si minimalizowa komunikacj przez dostarczenie jak najpeniejszychinformacji w pierwszej odpowiedzi. Chodzi o to, e jeli serwer nie dostarczywystarczaj cej iloci danych w odpowiedzi, klient bdzie musia wysa 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 oci 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 przedstawiam podstawowe za oenia technologii REST, opisa am API CRUDoraz pokaza am, jak projektowa zasoby RESTful. W przykadach uyte zosta y adnotacje JAX--RS 2.0, za pomoc których mona reprezentowa metody HTTP, i API klienckie, przy uyciuktórych mona odnosi si do zasobów. Ponadto zrobiam przegl d najlepszych praktyk projektowania usug typu RESTful.

W nastpnym rozdziale znajduje si rozszerzenie tych wiadomoci. Bardziej szczegóowo po-znasz zasady negocjowania treci, dostawców jednostek w JAX-RS 2.0, techniki obsugi bdów,sposoby kontrolowania wersji oraz kody odpowiedzi REST. Ponadto dowiesz si, w jaki spo-sób serwer moe wysya do klienta odpowiedzi przy uyciu strumieniowania i kawa kowania.








Skorowidz

A

adnotacja @Asynchronous, 72@Consumes, 34@DefaultValue, 90@Produces, 33@Suspended, 72@VerifyValue, 50@WebFilter, 82NotNull, 50Valid, 49ValidateOnExecution, 49

adnotacje JAX-RS, 26adres URL, 35

AMQP, Advanced Messaging Queing Protocol, 74 Apache Log4j, 47 API, 23

CRUD, 30GitHub, 113Graph portalu Facebook, 114klienta, 25

reaguj ce na bie co, 98REST, 46, 66, 68REST Facebooka, 69REST portalu GitHub, 111REST portalu Twitter, 117SSE, 102

aplikacjechmurowe, 107konsumenckie, 56macierzyste, 57sieciowe, 57

architektura mikrousugowa, 108niezaleno, 109podzia funkcjonalnoci, 109prostota, 108skalowalno, 109wyodrbnienie problemów, 108

architektura REST, 59asynchroniczne

obsugiwanie zada , 74przetwarzanie, 70

atrybuthref, 93method, 94rel, 94

autoryzacja, 54

B

Bean Validation, 49bezpieczestwo, 45bezpieczestwo metod, 18bezstanowo, 16biblioteka Log4j, 47b d

406, 34415, 34420, 87429, 80, 85

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









122

C

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

odpowiedzi, 64

ycia tokenu, 58czasowniki, 113czasowniki HTTP, 17, 21

D

dane JSON, 39osobowe, 48

dodanie metadanych, 25dokumentowanie usug, 95

dostawca tosamoci, 53usug, 53, 56

jednostek, 35dostp do zasobów REST, 25, 27dyrektywa QoS, 100dyrektywy nagówka Cache-Control, 65dzia anie gniazd sieciowych, 105

E

eksplorator API Graph, 115elementy architektury REST, 59

F

filtrograniczaj cy dania, 82rejestruj cy, 46

format JSON, 39funkcje interfejsu EventSource, 102funkcjonalnoci gniazd sieciowych, 106

G

gniazdo sieciowe, WebSocket, 104grant autoryzacji, 57

H

HATEOAS, 18, 92, 93

I

idempotentno metod, 18identyfikacja

metainformacji, 48

metod, 20osoby, 48reprezentacji zasobu, 22

identyfikator URI, 40identyfikator URI zasobu, 19implementacja

OAuth, 58 API, 23

informacje o awarii, 47interfejs

EventSource, 102

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

internacjonalizacja, 91IPN, 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, 83ChunkedInput, 38ChunkedOutput, 37

CoffeesResource, 49Filter, 82 JSONArray, 39 JSONParser, 39LoggingFilter, 47RateLimiter, 81, 84ResourceError, 52ResponseBuilder, 43StreamingOutput, 36VariantListBuilder, 34








Skorowidz

123

klasy JAX-RS, 26klient, 57kod

200, 68202, 73

304, 67, 69406, 34415, 34420, 87429, 80, 85odpowiedzi, 42, 43, 50

kolejka wiadomoci, 74komunikacja na bie co, 106

L

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

M

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

build(), 34

doFilter(), 84getBookInJSON(), 35getBookInXML(), 35getSize(), 36isCancelled(), 71isDone(), 71isReadable(), 36isWriteable(), 36

JSON Patch, 76prepareResponse(), 73readFrom(), 36

selectVariant(), 34writeTo(), 36metody

HTTP, Patrz danieidempotentne, 18uwierzytelniania, 27

mikrousugi, 107–110model

dojrza oci Richardsona, 16PubSubHubbub, 99strumieniowania, 100

N

nagówek Accept, 33, 41Cache-Control, 65, 66

Content-Language, 91Content-Length, 37Content-Type, 33ETag, 65, 68Expires, 65Last-Modified, 65Retry-After, 80, 84X-RateLimit-Remaining, 81

nagówki buforowania silne, 64sabe, 64

narzdzie

Advanced REST client, 29cURL, 27

JSONLint, 29Postman, 27, 29

negocjacja treci, 32poprzez adres URL, 35poprzez nagówki HTTP, 32

niezawodno, 16numer wersji, 41

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

O

OAuth, Open Authorization, 54OAuth 1.0, 57OAuth 2.0, 58obiekt

cacheControl, 66Variant, 34

obsuga bdów, 51, 113, 116, 119

kodów odpowiedzi, 50wyj tków, 50odpowiedzi REST, 31ograniczanie liczby da , 80–82, 114, 117okrelanie

wersji, 40wersji API, 41

OpenID Connect, 59operacje

asynchroniczne, 70dugotrwa e, 70









124

P

pliki WAR/EAR, 108POJO, 39poprawno usug REST, 49

portal Facebook, 114czynnoci zasobów, 116obsuga bdów, 116ograniczanie liczby da , 117wersjonowanie, 116

portal GitHub, 111akcje zasobów, 113obsuga bdów, 113ograniczanie liczby da , 114pobieranie informacji, 112wersjonowanie, 113

portal Twitter, 117dzia ania na zasobach, 118obsuga bdów, 119wersjonowanie, 119

POX, Plain Old XML, 17procedura

bookavailable, 102newbookadded, 102

procedury nasuchowe, 102proces

asynchronicznego przetwarzania, 71autoryzacji, 55

projektowaniewydajnych rozwi za , 63zasobów, 29, 31

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

przetwarzanieasynchroniczne, 70danych JSON, 39niskopoziomowe, 39

PuSH, 99, 104

Q

QoS, Quality of Service, 100

R

rejestrowanieinformacji, 46, 47treci, 48

da , 86REST, Representational State Transfer, 15RESTEasy, 69rodzaje

odpowiedzi REST, 31stronicowania, 88

rola identity provider, 53klient, 56principal, 53service provider, 53

serwer, 56uytkownik, 56rozszerzalno, 94

S

SAML, Security Assertion Markup Language, 53serializacja zasobów, 35serwer, 100skalowalno, 16SOAP, Simple Object Access Protocol, 15

sondowanie, polling, 98sondowanie spowolnione, 107sprawdzanie poprawnoci

danych, 29usug REST, 49

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

COMPLETED, 75PROCESSING, 75

statyczna negocjacja treci, 34stronicowanie

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

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








Skorowidz

125

T

tablica JSONArray, 90technologia

BOSH, 107

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

termin wyga nicia, 74testowanie

usug, 95typu RESTful, 25

token, 54dostpu, 57odwieania, 57, 58

tworzenie

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

typ MIME, 34typy

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

U

uchwyt sieciowy, WebHook, 103ukad projektu, 81, 90unikanie sondowania, 86usuga

GitHub, 104IPN, 104

usugi typu RESTful, 19utrata po czenia, 101uwierzytelnianie, 27, 53uzgodnienie, handshake, 107uycie gniazd sieciowych, 106

W

wdra anie usug typu RESTful, 25wersjonowanie API, 40weryfikacja poprawnoci danych, 50wze komunikacyjny, 99wiadomo

SSE, 101SSE z identyfikatorem, 101

wi zanieidentyfikatora ze zdarzeniem, 101nazw ze zdarzeniami, 101

widoczno, 16WSDL, Web Service Description Language, 15

wyj tek, 50CoffeeNotFoundException, 51wykrywalno, 45wysyanie

nagówka Accept, 42numeru wersji, 41

wzorce REST, 42

X

XMPP, 106

Z

zaciemnianie danych poufnych, 47zasady

buforowania, 64projektowania, 79

zasobyasynchroniczne, 73REST, 17RESTful, 19, 22

zdalne wywoywanie procedur, 17zdarzenia SSE, 100–103, 107uchwytów sieciowych, 103

ziarno JAXB, 39znaczniki ETag, 67, 68

dania

curl, 27, 85

w ptlach, 86 danieDELETE, 21GET, 21HEAD, 22OAuth, 55PATCH, 74, 76POST, 21, 26PUT, 21Upgrade, 104









126








http://program-partnerski.helion.pl/

REST - najlepsze praktyki i wzorece dla Java

Documents

Transcript of REST - najlepsze praktyki i wzorece dla Java