Cyfroteka.pl

klikaj i czytaj online

Cyfro
Czytomierz
00112 005655 13260114 na godz. na dobę w sumie
REST. Najlepsze praktyki i wzorce w języku Java - ebook/pdf
REST. Najlepsze praktyki i wzorce w języku Java - ebook/pdf
Autor: Liczba stron: 128
Wydawca: Helion Język publikacji: polski
ISBN: 978-83-283-0647-9 Data wydania:
Lektor:
Kategoria: ebooki >> komputery i informatyka >> programowanie >> java - programowanie
Porównaj ceny (książka, ebook, audiobook).

Usprawnij wymianę danych z usługą REST!

Postępująca cyfryzacja współczesnego świata wymaga coraz większej integracji przeróżnych systemów informatycznych. Nierzadko są to systemy znajdujące się w odległych lokalizacjach, napisane z wykorzystaniem różnych języków programowania i technologii. Jak zapewnić możliwość wymiany informacji między nimi? Usługi typu REST to jeden z najwygodniejszych sposobów!

Co to jest REST? Jak przygotować usługę tego typu? Jak ustrzec się przed błędami? Na te i wiele innych pytań odpowiada ta książka. Znajdziesz w niej najlepsze praktyki tworzenia usług REST z wykorzystaniem języka Java. Sięgnij po nią i dowiedz się, jak projektować zasoby i zapewniać im bezpieczeństwo oraz w jaki sposób przygotowywać usługi REST dla różnych wersji językowych. Odkryj, jak testować udostępnione zasoby i zagwarantować ich najwyższą wydajność oraz jaka przyszłość czeka usługi tego typu. Sprawdź też, jak wygląda API takich usług, jak GitHub, Twitter i Facebook (API Graph). Ta książka jest doskonałą lekturą dla wszystkich programistów chcących bezproblemowo tworzyć wydajne usługi typu REST.

Tematy opisane w książce:

Wydajne usługi REST w Twoim zasięgu!

Znajdź podobne książki Ostatnio czytane w tej kategorii

Darmowy fragment publikacji:

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ść Spis tre(cid:258)ci O autorce Podzi(cid:218)kowania O recenzentach Wst(cid:218)p Rozdzia(cid:239) 1. Podstawy REST Wprowadzenie do REST REST i bezstanowo(cid:258)(cid:202) Model dojrza(cid:239)o(cid:258)ci Richardsona Poziom 0 — zdalne wywo(cid:239)ywanie procedur Poziom 1 — zasoby REST Poziom 2 — dodatkowe czasowniki HTTP Poziom 3 — HATEOAS Bezpiecze(cid:241)stwo i idempotentno(cid:258)(cid:202) Bezpiecze(cid:241)stwo metod Idempotentno(cid:258)(cid:202) metod Zasady projektowe dotycz(cid:200)ce budowy us(cid:239)ug typu RESTful Wyznaczenie identyfikatorów URI zasobów Identyfikacja metod obs(cid:239)ugiwanych przez zasób Czasowniki HTTP w REST PUT czy POST Identyfikacja ró(cid:285)nych reprezentacji zasobu Implementowanie API API Javy dla us(cid:239)ug RESTful (JAX-RS) 7 8 9 11 15 16 16 16 17 17 17 18 18 18 18 19 19 20 21 22 22 23 23 Kup książkęPoleć książkę REST. Najlepsze praktyki i wzorce w j(cid:266)zyku Java Wdra(cid:285)anie us(cid:239)ug typu RESTful Testowanie us(cid:239)ug typu RESTful API klienta w JAX-RS 2.0 Uzyskiwanie dost(cid:218)pu do zasobów RESTful Inne narz(cid:218)dzia Najlepsze praktyki projektowania zasobów Zalecana lektura Podsumowanie Rozdzia(cid:239) 2. Projektowanie zasobów Rodzaje odpowiedzi REST Negocjacja tre(cid:258)ci Negocjacja tre(cid:258)ci przy u(cid:285)yciu nag(cid:239)ówków HTTP Negocjacja tre(cid:258)ci poprzez adres URL Dostawcy jednostek i ró(cid:285)ne reprezentacje StreamingOutput ChunkedOutput Jersey i JSON Wersjonowanie API Okre(cid:258)lanie wersji w identyfikatorze URI Numer wersji w parametrze zapytaniowym (cid:285)(cid:200)dania Okre(cid:258)lanie numeru wersji w nag(cid:239)ówku Accept Kody odpowiedzi i wzorce REST Zalecana lektura Podsumowanie Rozdzia(cid:239) 3. Bezpiecze(cid:241)stwo i wykrywalno(cid:258)(cid:202) Rejestrowanie informacji w API REST Najlepsze praktyki rejestrowania informacji w API REST Sprawdzanie poprawno(cid:258)ci us(cid:239)ug REST Obs(cid:239)uga wyj(cid:200)tków i kodów odpowiedzi zwi(cid:200)zanych z weryfikacj(cid:200) poprawno(cid:258)ci danych Obs(cid:239)uga b(cid:239)(cid:218)dów w us(cid:239)ugach typu RESTful Uwierzytelnianie i autoryzacja Co to jest uwierzytelnianie Co to jest autoryzacja Ró(cid:285)nice mi(cid:218)dzy OAuth 2.0 i OAuth 1.0 Tokeny od(cid:258)wie(cid:285)ania a tokeny dost(cid:218)pu Najlepsze praktyki przy implementacji OAuth w API REST OpenID Connect Elementy architektury REST Zalecana lektura Podsumowanie 4 25 25 25 27 29 29 30 30 31 31 32 32 35 35 36 37 38 40 40 41 41 42 43 44 45 46 47 49 50 51 52 53 54 57 57 58 59 59 61 62 Kup książkęPoleć książkę Spis tre(cid:286)ci Rozdzia(cid:239) 4. Projektowanie wydajnych rozwi(cid:200)za(cid:241) Zasady buforowania Szczegó(cid:239)y buforowania Typy nag(cid:239)ówków buforowania Nag(cid:239)ówek Cache-Control i dyrektywy Nag(cid:239)ówek Cache-Control i API REST Znaczniki ETag API REST Facebooka i nag(cid:239)ówki ETag Asynchroniczne i d(cid:239)ugotrwa(cid:239)e operacje w REST Asynchroniczne przetwarzanie (cid:285)(cid:200)da(cid:241) i odpowiedzi Najlepsze praktyki pracy z zasobami asynchronicznymi Wysy(cid:239)anie kodu statusu 202 Accepted Ustawianie terminu wyga(cid:258)ni(cid:218)cia dla obiektów w kolejce Asynchroniczne obs(cid:239)ugiwanie zada(cid:241) przy u(cid:285)yciu kolejek wiadomo(cid:258)ci Metoda HTTP PATCH i cz(cid:218)(cid:258)ciowe aktualizacje JSON Patch Zalecana lektura Podsumowanie Rozdzia(cid:239) 5. Zaawansowane zasady projektowania Techniki ograniczania liczby (cid:285)(cid:200)da(cid:241) Uk(cid:239)ad projektu Szczegó(cid:239)owa analiza przyk(cid:239)adu ograniczania liczby (cid:285)(cid:200)da(cid:241) Najlepsze praktyki pozwalaj(cid:200)ce unikn(cid:200)(cid:202) przekroczenia limitu (cid:285)(cid:200)da(cid:241) przez klienty Stronicowanie odpowiedzi Rodzaje stronicowania Uk(cid:239)ad projektu Internacjonalizacja i lokalizacja Ró(cid:285)ne tematy HATEOAS API REST portalu PayPal i HATEOAS REST i rozszerzalno(cid:258)(cid:202) Inne tematy zwi(cid:200)zane z API REST Testowanie us(cid:239)ug typu RESTful Zalecana lektura Podsumowanie Rozdzia(cid:239) 6. Nowe standardy i przysz(cid:239)o(cid:258)(cid:202) technologii REST API reaguj(cid:200)ce na bie(cid:285)(cid:200)co Sondowanie Model PuSH — PubSubHubbub Model strumieniowania Uchwyty sieciowe Gniazda sieciowe 63 64 64 64 65 66 67 69 70 70 73 73 74 74 74 76 77 77 79 80 81 82 86 87 88 90 91 92 92 93 94 94 95 96 96 97 98 98 99 100 103 104 5 Kup książkęPoleć książkę 106 106 107 107 108 108 108 109 109 109 109 110 111 111 112 113 113 113 114 114 116 116 116 117 117 118 119 119 119 119 121 REST. Najlepsze praktyki i wzorce w j(cid:266)zyku Java Inne API i technologie do komunikacji na bie(cid:285)(cid:200)co XMPP BOSH poprzez XMPP Porównanie uchwytów sieciowych, gniazd sieciowych i zdarze(cid:241) wysy(cid:239)anych przez serwer REST i mikrous(cid:239)ugi Prostota Wyodr(cid:218)bnienie problemów Skalowalno(cid:258)(cid:202) Wyra(cid:283)ny podzia(cid:239) funkcjonalno(cid:258)ci Niezale(cid:285)no(cid:258)(cid:202) od j(cid:218)zyka programowania Zalecana lektura Podsumowanie Dodatek A Przegl(cid:200)d API REST portalu GitHub Pobieranie informacji z portalu GitHub Czasowniki i akcje zasobów Wersjonowanie Obs(cid:239)uga b(cid:239)(cid:218)dów Ograniczanie liczby (cid:285)(cid:200)da(cid:241) Przegl(cid:200)d API Graph portalu Facebook Czasowniki i czynno(cid:258)ci zasobów Wersjonowanie Obs(cid:239)uga b(cid:239)(cid:218)dów Ograniczanie liczby (cid:285)(cid:200)da(cid:241) Przegl(cid:200)d API portalu Twitter Czasowniki i dzia(cid:239)ania na zasobach Wersjonowanie Obs(cid:239)uga b(cid:239)(cid:218)dów Zalecana lektura Podsumowanie Skorowidz 6 Kup książkęPoleć książkę 1 Podstawy REST Us(cid:239)ugi sieciowe w tradycyjnej technologii SOA, umo(cid:285)liwiaj(cid:200)ce zró(cid:285)nicowan(cid:200) komunikacj(cid:218) mi(cid:218)dzy aplikacjami, istniej(cid:200) ju(cid:285) od pewnego czasu. Jednym ze sposobów obs(cid:239)ugi tej komuni- kacji jest u(cid:285)ycie technologii Simple Object Access Protocol (SOAP) i Web Service Description Language (WSDL). S(cid:200) to standardy oparte na formacie XML doskonale sprawdzaj(cid:200)ce si(cid:218), gdy mi(cid:218)dzy us(cid:239)ugami jest (cid:258)cis(cid:239)y kontakt. Ale nasta(cid:239)a era us(cid:239)ug rozproszonych. Teraz ró(cid:285)ne klienty z internetu, urz(cid:200)dzenia przeno(cid:258)ne, jak równie(cid:285) inne us(cid:239)ugi (wewn(cid:218)trzne i zewn(cid:218)trzne) mog(cid:200) u(cid:285)ywa(cid:202) interfejsów API udost(cid:218)pnianych przez ró(cid:285)nych dostawców i ró(cid:285)ne platformy open source. To sprawia, (cid:285)e potrzebne s(cid:200) technologie (cid:239)atwej wymiany informacji mi(cid:218)dzy us(cid:239)ugami rozproszonymi w ró(cid:285)nych miejscach, z przewidywalnymi, solidnymi, (cid:258)ci(cid:258)le zdefiniowanymi interfejsami. Protokó(cid:239) HTTP 1.1, zdefiniowany w dokumencie RFC 2616, jest powszechnie u(cid:285)ywany w roz- proszonych systemach hipermedialnych. Technologia Representational State Transfer (REST) bazuje na HTTP i mo(cid:285)e by(cid:202) u(cid:285)ywana wsz(cid:218)dzie tam, gdzie ten protokó(cid:239). W tym rozdziale przed- stawione s(cid:200) podstawowe wiadomo(cid:258)ci na temat projektowania us(cid:239)ug typu RESTful oraz u(cid:285)ywa- nia takich us(cid:239)ug za pomoc(cid:200) standardowych interfejsów API Javy. W rozdziale omówiono nast(cid:218)puj(cid:200)ce zagadnienia: (cid:81) Wprowadzenie do technologii REST. (cid:81) Bezpiecze(cid:241)stwo i idempotentno(cid:258)(cid:202). (cid:81) Zasady projektowe dotycz(cid:200)ce budowy us(cid:239)ug typu RESTful. (cid:81) Standardowe API Javy dla us(cid:239)ug typu RESTful. (cid:81) Najlepsze techniki projektowania us(cid:239)ug typu RESTful. Kup książkęPoleć książkę REST. Najlepsze praktyki i wzorce w j(cid:266)zyku Java Wprowadzenie do REST REST to styl architektoniczny zgodny z takimi standardami sieciowymi jak czasowniki HTTP i identyfikatory URI. Obowi(cid:200)zuj(cid:200) w nim nast(cid:218)puj(cid:200)ce zasady: (cid:81) Wszystkie zasoby okre(cid:258)la identyfikator URI. (cid:81) Ka(cid:285)dy zasób mo(cid:285)e mie(cid:202) liczne reprezentacje. (cid:81) Ka(cid:285)dy zasób mo(cid:285)na pobra(cid:202), zmodyfikowa(cid:202), utworzy(cid:202) i usun(cid:200)(cid:202) standardowymi metodami HTTP. (cid:81) Na serwerze nie s(cid:200) przechowywane (cid:285)adne informacje o stanie. REST i bezstanowo(cid:258)(cid:202) W REST obowi(cid:200)zuje zasada bezstanowo(cid:258)ci. Ka(cid:285)de (cid:285)(cid:200)danie przesy(cid:239)ane przez klienta do ser- wera musi zawiera(cid:202) wszystkie informacje potrzebne do obs(cid:239)ugi tego zdarzenia. To poprawia widoczno(cid:258)(cid:202), niezawodno(cid:258)(cid:202) i skalowalno(cid:258)(cid:202) (cid:285)(cid:200)da(cid:241). Poprawa widoczno(cid:258)ci wynika z tego, (cid:285)e system monitoruj(cid:200)cy (cid:285)(cid:200)dania nie musi szuka(cid:202) szcze- gó(cid:239)ów poza (cid:285)(cid:200)daniami. Niezawodno(cid:258)(cid:202) poprawia si(cid:218) dzi(cid:218)ki wyeliminowaniu punktów kontrol- nych i wznowienia w przypadku cz(cid:218)(cid:258)ciowych niepowodze(cid:241) operacji. Poprawa skalowalno(cid:258)ci jest efektem zwi(cid:218)kszenia liczby (cid:285)(cid:200)da(cid:241), które jest w stanie przetworzy(cid:202) serwer, co jest mo(cid:285)liwe dzi(cid:218)ki temu, (cid:285)e serwer nie musi przechowywa(cid:202) informacji o stanie. Roy Fielding napisa(cid:239) doktorat na temat stylu architektonicznego REST, w którym szczegó(cid:239)owo opisa(cid:239) bez- stanowo(cid:258)(cid:202) tej technologii. Wi(cid:218)cej informacji na ten temat mo(cid:285)na znale(cid:283)(cid:202) pod adresem http://www.ics. uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm. To s(cid:200) podstawowe wiadomo(cid:258)ci o technologii REST. Teraz zajmiemy si(cid:218) ró(cid:285)nymi poziomami dojrza(cid:239)o(cid:258)ci i zobaczymy, gdzie po(cid:258)ród nich mie(cid:258)ci si(cid:218) ta technologia. Model dojrza(cid:239)o(cid:258)ci Richardsona Model dojrza(cid:239)o(cid:258)ci Richardsona to opracowany przez Leonarda Richardsona model opisuj(cid:200)- cy podstawy REST pod wzgl(cid:218)dem zasobów, czasowników i hipermediów. Punktem pocz(cid:200)t- kowym tego modelu jest wykorzystanie HTTP jako warstwy transportowej. Ukazuje to poni(cid:285)- szy schemat. 16 Kup książkęPoleć książkę Rozdzia(cid:225) 1. • Podstawy REST Poziom 0 — zdalne wywo(cid:239)ywanie procedur Do poziomu 0 zalicza si(cid:218) przesy(cid:239)anie danych przy u(cid:285)yciu technologii SOAP i XML-RPC jako POX (ang. Plain Old XML — zwyk(cid:239)y XML). U(cid:285)ywana jest tylko metoda POST. Jest to najprost- szy sposób budowania aplikacji SOA z jedn(cid:200) metod(cid:200) POST i przy u(cid:285)yciu formatu XML do ko- munikacji mi(cid:218)dzy us(cid:239)ugami. Poziom 1 — zasoby REST Na poziomie 1 u(cid:285)ywane s(cid:200) metody POST, a zamiast funkcji i przekazywania argumentów wy- korzystuje si(cid:218) identyfikatory URI REST. Zatem nadal u(cid:285)ywana jest tylko jedna metoda HTTP. Zalet(cid:200) tego poziomu w stosunku do zerowego jest podzia(cid:239) z(cid:239)o(cid:285)onej funkcjonalno(cid:258)ci na kilka zasobów za pomoc(cid:200) jednej metody POST s(cid:239)u(cid:285)(cid:200)cej do komunikacji mi(cid:218)dzy us(cid:239)ugami. Poziom 2 — dodatkowe czasowniki HTTP Na poziomie drugim jest wi(cid:218)cej czasowników, np. GET, HEAD, DELETE, PUT i oczywi(cid:258)cie POST. Poziom ten reprezentuje rzeczywisty przypadek u(cid:285)ycia technologii REST, w której wykorzy- stuje si(cid:218) ró(cid:285)ne czasowniki HTTP do wykonywania ró(cid:285)nych (cid:285)(cid:200)da(cid:241), a system mo(cid:285)e zawiera(cid:202) wiele zasobów. 17 Kup książkęPoleć książkę REST. Najlepsze praktyki i wzorce w j(cid:266)zyku Java Poziom 3 — HATEOAS HATEOAS (ang. Hypermedia as the Engine of Application State — hipermedia jako mecha- nizm obs(cid:239)ugi stanu aplikacji) reprezentuje najwy(cid:285)szy stopie(cid:241) dojrza(cid:239)o(cid:258)ci w modelu Richard- sona. Odpowiedzi na (cid:285)(cid:200)dania klientów zawieraj(cid:200) elementy hipermedialne, przy u(cid:285)yciu których klient mo(cid:285)e zdecydowa(cid:202), co robi(cid:202) dalej. Zasady te u(cid:239)atwiaj(cid:200) wykrywanie us(cid:239)ug i sprawiaj(cid:200), (cid:285)e odpowiedzi s(cid:200) bardziej zrozumia(cid:239)e. Tocz(cid:200) si(cid:218) dyskusje na temat tego, czy HATEOAS rzeczy- wi(cid:258)cie spe(cid:239)nia wymagania RESTful, poniewa(cid:285) reprezentacja zawiera o wiele wi(cid:218)cej informa- cji ni(cid:285) tylko opis zasobu. W rozdziale 5. przedstawiam par(cid:218) przyk(cid:239)adów pokazuj(cid:200)cych, jak za- implementowano HATEOAS jako cz(cid:218)(cid:258)(cid:202) API niektórych platform, np. PayPal. W nast(cid:218)pnym podrozdziale wyja(cid:258)niam poj(cid:218)cia bezpiecze(cid:241)stwo i idempotentno(cid:258)(cid:202), które s(cid:200) bar- dzo wa(cid:285)ne w us(cid:239)ugach RESTful. Bezpiecze(cid:241)stwo i idempotentno(cid:258)(cid:202) W poni(cid:285)szych dwóch podrozdzia(cid:239)ach dok(cid:239)adniej wyja(cid:258)niam znaczenie bezpiecze(cid:241)stwa i idem- potentno(cid:258)ci metod. Bezpiecze(cid:241)stwo metod Bezpieczna metoda to taka, która nie zmienia stanu na serwerze. Warunek ten spe(cid:239)nia na przy- k(cid:239)ad metoda GET /v1/coffees/orders/1234. Bezpieczne metody, do których zaliczaj(cid:200) si(cid:218) GET i HEAD, mo(cid:285)na buforowa(cid:202). Metoda PUT nie jest bezpieczna, poniewa(cid:285) tworzy lub modyfikuje zasoby na serwerze. To samo dotyczy metody POST. Z kolei metoda DELETE nie jest bezpieczna, poniewa(cid:285) usuwa zasoby z serwera. Idempotentno(cid:258)(cid:202) metod Metoda idempotentna to taka, która zwraca taki sam wynik niezale(cid:285)nie od tego, ile razy zosta- nie wywo(cid:239)ana. Metoda GET jest idempotentna, poniewa(cid:285) niezale(cid:285)nie od tego, ile razy si(cid:218) j(cid:200) wywo(cid:239)a, zawsze zwraca tak(cid:200) sam(cid:200) odpowied(cid:283). Metoda PUT te(cid:285) jest idempotentna, poniewa(cid:285) wielokrotne jej wywo(cid:239)anie powoduje aktualizacj(cid:218) tego samego zasobu i nie zmienia to wyniku. 18 Kup książkęPoleć książkę Rozdzia(cid:225) 1. • Podstawy REST Metoda POST nie jest idempotentna, poniewa(cid:285) jej wielokrotne wywo(cid:239)anie mo(cid:285)e dawa(cid:202) ró(cid:285)ne skutki i powodowa(cid:202) powstanie wielu zasobów. Metoda DELETE jest idempotentna, gdy(cid:285) usuni(cid:218)ty zasób znika i powtórne wywo(cid:239)anie tej samej metody niczego nie zmieni. Zasady projektowe dotycz(cid:200)ce budowy us(cid:239)ug typu RESTful Poni(cid:285)ej w punktach przedstawiam proces projektowania, tworzenia i testowania us(cid:239)ug typu RESTful. Dalej znajduje si(cid:218) dok(cid:239)adniejszy opis ka(cid:285)dego z tych etapów: (cid:81) Wyznaczenie identyfikatorów URI zasobów. Polega na wybraniu rzeczowników do reprezentowania zasobu. (cid:81) Identyfikacja metod obs(cid:239)ugiwanych przez zasób. Polega na wybraniu metod HTTP do wykonywania operacji CRUD (ang. create, read, update, delete — utworzenie, odczytanie, aktualizacja, usuni(cid:218)cie). (cid:81) Identyfikacja ró(cid:285)nych reprezentacji zasobu. Polega na wybraniu, czy zasób b(cid:218)dzie reprezentowany w formacie JSON, XML, HTML, czy tekstowym. (cid:81) Implementacja us(cid:239)ug RESTful przy u(cid:285)yciu API JAX-RS. Interfejs API nale(cid:285)y zaimplementowa(cid:202) na podstawie specyfikacji JAX-RS. (cid:81) Wdro(cid:285)enie us(cid:239)ug RESTful. Wdro(cid:285)enie us(cid:239)ugi w kontenerze aplikacji, np. Tomcat, GlassFish lub WildFly. Na przyk(cid:239)adach pokazuj(cid:218), jak tworzy si(cid:218) pliki WAR, i prezentuj(cid:218) sposób wdro(cid:285)enia na serwerze GlassFish 4.0. Poza tym przedstawiony przyk(cid:239)ad dzia(cid:239)a w ka(cid:285)dym kontenerze zgodnym z Java EE 7. (cid:81) Testowanie us(cid:239)ug RESTful. Polega na napisaniu API klienta do testowania us(cid:239)ug lub u(cid:285)yciu narz(cid:218)dzi cURL albo przegl(cid:200)darkowych do testowania (cid:285)(cid:200)da(cid:241) REST. Wyznaczenie identyfikatorów URI zasobów Zasoby RESTful s(cid:200) identyfikowane przez identyfikatory URI. Dzi(cid:218)ki temu technologia REST jest rozszerzalna. Poni(cid:285)sza tabela zawiera przyk(cid:239)ady identyfikatorów URI, które mog(cid:200) reprezentowa(cid:202) ró(cid:285)ne za- soby w systemie. 19 Kup książkęPoleć książkę REST. Najlepsze praktyki i wzorce w j(cid:266)zyku Java URI Opis Mo(cid:285)liwa reprezentacja kolekcji zasobów ksi(cid:200)(cid:285)kowych w bibliotece. /v1/library/books /v1/library/books/isbn/12345678 Mo(cid:285)liwa reprezentacja jednej ksi(cid:200)(cid:285)ki identyfikowanej przez numer /v1/coffees /v1/coffees/orders /v1/coffees/orders/123 /v1/users/1235 /v1/users/5034/books ISBN 123456. Mo(cid:285)liwa reprezentacja wszystkich kaw sprzedanych w kawiarni. Mo(cid:285)liwa reprezentacja wszystkich zamówionych kaw w kawiarni. Mo(cid:285)liwa reprezentacja pojedynczego zamówienia kawy o identyfikatorze 123. Mo(cid:285)liwa reprezentacja u(cid:285)ytkownika o identyfikatorze w systemie 1235. Mo(cid:285)liwa reprezentacja wszystkich ksi(cid:200)(cid:285)ek u(cid:285)ytkownika o identyfikatorze 5034. Wszystkie przedstawione identyfikatory s(cid:200) zbudowane wg jasnego wzorca, który klient mo(cid:285)e bez trudu zinterpretowa(cid:202). Wszystkie te zasoby mog(cid:200) mie(cid:202) liczne reprezentacje, np. w forma- cie JSON, XML, HTML lub tekstowym, i mo(cid:285)na nimi zarz(cid:200)dza(cid:202) za pomoc(cid:200) metod GET, PUT, POST i DELETE. Identyfikacja metod obs(cid:239)ugiwanych przez zasób Czasowniki HTTP stanowi(cid:200) wa(cid:285)ny sk(cid:239)adnik jednolitego ograniczenia interfejsu, które definiu- je zwi(cid:200)zek mi(cid:218)dzy czynno(cid:258)ciami opisywanymi przez dany czasownik w stosunku do opisanego za pomoc(cid:200) rzeczowników zasobu REST. Poni(cid:285)sza tabela zawiera zestawienie metod HTTP i opis powodowanych przez nie zdarze(cid:241) oraz prosty przyk(cid:239)ad kolekcji ksi(cid:200)(cid:285)ek w bibliotece. Metoda HTTP URI zasobu Opis GET GET POST DELETE PUT PATCH /library/books /library/books/isbn/12345678 Pobiera list(cid:218) ksi(cid:200)(cid:285)ek. Pobiera ksi(cid:200)(cid:285)k(cid:218) o numerze ISBN 12345678. Tworzy nowe zamówienie ksi(cid:200)(cid:285)ki. /library/books /library/books/isbn/12345678 Usuwa ksi(cid:200)(cid:285)k(cid:218) o numerze ISBN 12345678. /library/books/isbn/12345678 Aktualizuje ksi(cid:200)(cid:285)k(cid:218) o numerze ISBN 12345678. /library/books/isbn/12345678 Cz(cid:218)(cid:258)ciowo aktualizuje ksi(cid:200)(cid:285)k(cid:218) o numerze ISBN 12345678. W kolejnym podrozdziale znajduje si(cid:218) opis zastosowania ka(cid:285)dego z czasowników HTTP w kon- tek(cid:258)cie REST. 20 Kup książkęPoleć książkę Rozdzia(cid:225) 1. • Podstawy REST Czasowniki HTTP w REST Czasowniki HTTP stanowi(cid:200) dla serwera informacj(cid:218) o tym, co ma zrobi(cid:202) z otrzymanymi danymi. GET GET to najprostsza metoda HTTP pozwalaj(cid:200)ca uzyska(cid:202) dost(cid:218)p do zasobu. Gdy klient kliknie adres URL w przegl(cid:200)darce internetowej, aplikacja ta wysy(cid:239)a (cid:285)(cid:200)danie GET pod ten w(cid:239)a(cid:258)nie ad- res. Metoda GET jest bezpieczna i idempotentna. (cid:191)(cid:200)dania wysy(cid:239)ane t(cid:200) metod(cid:200) s(cid:200) buforowane i mog(cid:200) zawiera(cid:202) parametry. Poni(cid:285)ej znajduje si(cid:218) proste (cid:285)(cid:200)danie GET pobieraj(cid:200)ce wszystkich aktywnych u(cid:285)ytkowników: curl http://api.foo.com/v1/users/12345?active=true POST Metoda POST s(cid:239)u(cid:285)y do tworzenia zasobów. (cid:191)(cid:200)dania wysy(cid:239)ane przy u(cid:285)yciu tej metody nie s(cid:200) idempotentne ani bezpieczne. Wielokrotne wywo(cid:239)ania mog(cid:200) spowodowa(cid:202) utworzenie wielu zasobów. (cid:191)(cid:200)danie POST powinno powodowa(cid:202) uniewa(cid:285)nienie odpowiedniego elementu w buforze, je(cid:258)li taki istnieje. W (cid:285)(cid:200)daniach POST nie zaleca si(cid:218) stosowania parametrów zapytaniowych. Poni(cid:285)ej znajduje si(cid:218) (cid:285)(cid:200)danie utworzenia u(cid:285)ytkownika: curl –X POST -d { name : Jan Kowalski , username : jkow , phone : 412-344-5644 } http://api.foo.com/v1/users PUT Metoda PUT s(cid:239)u(cid:285)y do aktualizowania zasobów. Jest ona idempotentna, ale nie jest bezpieczna. Wielokrotne (cid:285)(cid:200)dania tego typu powinny dawa(cid:202) taki sam efekt w postaci zaktualizowania zasobu. (cid:191)(cid:200)dania PUT powinny uniewa(cid:285)nia(cid:202) zawarto(cid:258)(cid:202) bufora, je(cid:258)li taka istnieje. Poni(cid:285)ej znajduje si(cid:218) przyk(cid:239)ad (cid:285)(cid:200)dania PUT aktualizuj(cid:200)cego u(cid:285)ytkownika: curl –X PUT -d { phone : 413-344-5644 } http://api.foo.com/v1/users DELETE Metoda DELETE s(cid:239)u(cid:285)y do usuwania zasobów. Jest idempotentna, ale nie jest bezpieczna. Idem- potentno(cid:258)(cid:202) wynika z tego, (cid:285)e zgodnie ze specyfikacj(cid:200) RFC 2616 skutki uboczne dowolnej wi(cid:218)k- szej od zera liczby (cid:285)(cid:200)da(cid:241) s(cid:200) takie same jak jednego (cid:285)(cid:200)dania. Oznacza to, (cid:285)e po usuni(cid:218)ciu zaso- bu kolejne wywo(cid:239)ania metody DELETE nic nie zmieniaj(cid:200). 21 Kup książkęPoleć książkę REST. Najlepsze praktyki i wzorce w j(cid:266)zyku Java Poni(cid:285)ej znajduje si(cid:218) przyk(cid:239)adowe (cid:285)(cid:200)danie usuwaj(cid:200)ce u(cid:285)ytkownika: curl –X DELETE http://foo.api.com/v1/users/1234 HEAD (cid:191)(cid:200)dania typu HEAD s(cid:200) podobne do GET. Ró(cid:285)nica mi(cid:218)dzy nimi polega na tym, (cid:285)e w odpowiedzi na (cid:285)(cid:200)danie HEAD zwracane s(cid:200) tylko nag(cid:239)ówki HTTP, bez tre(cid:258)ci. Metoda HEAD jest idempotentna i bezpieczna. Poni(cid:285)ej znajduje si(cid:218) przyk(cid:239)adowe (cid:285)(cid:200)danie HEAD wysy(cid:239)ane za pomoc(cid:200) narz(cid:218)dzia cURL: curl –X HEAD http://foo.api.com/v1/users Je(cid:258)li zasób jest du(cid:285)y, to za pomoc(cid:200) (cid:285)(cid:200)dania HEAD mo(cid:285)na sprawdzi(cid:202), czy co(cid:258) si(cid:218) w nim zmieni(cid:239)o, zanim si(cid:218) je pobierze przy u(cid:285)yciu (cid:285)(cid:200)dania GET. PUT czy POST Zgodnie z dokumentem RFC ró(cid:285)nica mi(cid:218)dzy metodami PUT i POST dotyczy identyfikatora URI (cid:285)(cid:200)dania. W metodzie POST przes(cid:239)any identyfikator URI definiuje jednostk(cid:218), która ma obs(cid:239)u(cid:285)y(cid:202) (cid:285)(cid:200)danie. W (cid:285)(cid:200)daniu PUT natomiast identyfikator URI zawiera t(cid:218) jednostk(cid:218). A zatem POST /v1/coffees/orders oznacza utworzenie nowego zasobu i zwrócenie opisuj(cid:200)cego go identyfikatora. PUT /v1/coffees/orders/1234 oznacza natomiast aktualizacj(cid:218) zasobu o iden- tyfikatorze 1234, je(cid:258)li taki istnieje. Je(cid:258)li nie ma takiego zasobu, zostanie utworzone nowe za- mówienie, do którego identyfikacji zostanie u(cid:285)yty URI orders/1234. Zarówno metody PUT, jak i POST mo(cid:285)na u(cid:285)ywa(cid:202) do tworzenia i aktualizacji zasobów. Wybór jednej z nich zale(cid:285)y g(cid:239)ównie od tego, czy potrzebna jest idempotentno(cid:258)(cid:202) metody, oraz od lokalizacji zasobu. W nast(cid:218)pnym podrozdziale dowiesz si(cid:218), jak identyfikowa(cid:202) ró(cid:285)ne reprezentacje zasobu. Identyfikacja ró(cid:285)nych reprezentacji zasobu Zasoby RESTful s(cid:200) jednostkami abstrakcyjnymi, które przed przes(cid:239)aniem do klienta trzeba pod- da(cid:202) serializacji do jakiego(cid:258) reprezentacyjnego formatu. W(cid:258)ród najcz(cid:218)(cid:258)ciej u(cid:285)ywanych repre- zentacji mo(cid:285)na wymieni(cid:202) XML, JSON, HTML i zwyk(cid:239)y tekst. Zasób mo(cid:285)e dostarcza(cid:202) kliento- wi reprezentacj(cid:218) w zale(cid:285)no(cid:258)ci od tego, co klient ten jest w stanie przyj(cid:200)(cid:202). Klient mo(cid:285)e okre(cid:258)li(cid:202) preferowane przez siebie j(cid:218)zyki i typy mediów. Nazywa si(cid:218) to negocjacj(cid:200) tre(cid:258)ci i zosta(cid:239)o szcze- gó(cid:239)owo opisane w rozdziale 2. 22 Kup książkęPoleć książkę Rozdzia(cid:225) 1. • Podstawy REST Implementowanie API Wiesz ju(cid:285) mniej wi(cid:218)cej, jak projektowa(cid:202) zasoby RESTful i jakich czasowników HTTP u(cid:285)ywa(cid:202) do wykonywania ró(cid:285)nych dzia(cid:239)a(cid:241) na tych zasobach, wi(cid:218)c mo(cid:285)emy przej(cid:258)(cid:202) do kwestii imple- mentowania API i budowania us(cid:239)ugi typu RESTful. G(cid:239)ównym tematem tego podrozdzia(cid:239)u jest: (cid:81) API Javy dla us(cid:239)ug RESTful (JAX-RS). API Javy dla us(cid:239)ug RESTful (JAX-RS) API Javy dla us(cid:239)ug RESTful s(cid:239)u(cid:285)y do budowania i rozwijania aplikacji wg zasad technologii REST. Przy u(cid:285)yciu JAX-RS mo(cid:285)na udost(cid:218)pnia(cid:202) obiekty Javy jako us(cid:239)ugi sieciowe typu RESTful, które s(cid:200) niezale(cid:285)ne od podstawowej technologii i u(cid:285)ywaj(cid:200) prostego API opartego na adnotacjach. Najnowsza wersja specyfikacji to JAX-RS 2.0. Od wersji JAX-RS 1.0 ró(cid:285)ni si(cid:218) przede wszystkim: (cid:81) narz(cid:218)dziami do sprawdzania poprawno(cid:258)ci ziaren, (cid:81) obs(cid:239)ug(cid:200) API klienta, (cid:81) mo(cid:285)liwo(cid:258)ci(cid:200) wykonywania wywo(cid:239)a(cid:241) asynchronicznych. Implementacja specyfikacji JAX-RS nazywa si(cid:218) Jersey. Wszystkie wymienione tematy zosta(cid:239)y szczegó(cid:239)owo opisane w kolejnych rozdzia(cid:239)ach. Przed- stawiam prosty przyk(cid:239)ad kawiarni, w którym mo(cid:285)na utworzy(cid:202) zasób REST o nazwie Coffees- Resource o nast(cid:218)puj(cid:200)cych umiej(cid:218)tno(cid:258)ciach: (cid:81) podanie szczegó(cid:239)ów z(cid:239)o(cid:285)onych zamówie(cid:241), (cid:81) tworzenie nowych zamówie(cid:241), (cid:81) sprawdzenie informacji o wybranym zamówieniu. Tworzenie zasobu RESTful zaczniemy od utworzenia obiektu Javy o nazwie CoffeesResource. Poni(cid:285)ej znajduje si(cid:218) przyk(cid:239)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(cid:285)szym kodzie zosta(cid:239) utworzony niewielki obiekt Javy o nazwie CoffeesResource. Klas(cid:218) t(cid:218) opatrzy(cid:239)am adnotacj(cid:200) @Path( v1/coffees ) okre(cid:258)laj(cid:200)c(cid:200) (cid:258)cie(cid:285)k(cid:218) URI, dla której klasa ta obs(cid:239)uguje (cid:285)(cid:200)dania. 23 Kup książkęPoleć książkę REST. Najlepsze praktyki i wzorce w j(cid:266)zyku Java 2. Nast(cid:218)pnie definiujemy metod(cid:218) o nazwie getCoffeeList(). Ma ona nast(cid:218)puj(cid:200)ce adnotacje: (cid:81) @GET: oznacza, (cid:285)e metoda reprezentuje (cid:285)(cid:200)danie HTTP GET. (cid:81) @PATH: w tym przypadku (cid:285)(cid:200)dania GET zasobu v1/coffees/orders b(cid:218)d(cid:200) obs(cid:239)ugiwane przez metod(cid:218) getCoffeeList(). (cid:81) @Produces: definiuje typy mediów zwracane przez ten zasób. W omawianym przyk(cid:239)adzie okre(cid:258)lono typ mediów MediaType.APPLICATION_JSON, którego warto(cid:258)(cid:202) to application/json. 3. Inna metoda tworz(cid:200)ca zamówienie wygl(cid:200)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(cid:200)ca nast(cid:218)puj(cid:200)ce adnotacje: (cid:81) @POST: oznacza, (cid:285)e metoda reprezentuje (cid:285)(cid:200)danie HTTP POST. (cid:81) @Consumes: definiuje przyjmowane przez zasób typy mediów. W omawianym przyk(cid:239)adzie okre(cid:258)lono typ mediów MediaType.APPLICATION_JSON, którego warto(cid:258)(cid:202) to application/json. (cid:81) @Produces: definiuje typy mediów zwracane przez ten zasób. W omawianym przyk(cid:239)adzie okre(cid:258)lono typ mediów MediaType.APPLICATION_JSON, którego warto(cid:258)(cid:202) to application/json. (cid:81) @ValidateOnExecution: okre(cid:258)la, dla których metod parametry i warto(cid:258)ci zwrotne maj(cid:200) by(cid:202) sprawdzane. Szerzej o adnotacjach @ValidateOnExecution i @Valid pisz(cid:218) w rozdziale 3. Jak wida(cid:202), zmiana prostego obiektu Javy w us(cid:239)ug(cid:218) REST jest bardzo (cid:239)atwa. Teraz obejrzymy podklas(cid:218) klasy Application, która b(cid:218)dzie zawiera(cid:239)a definicje komponentów aplikacji JAX-RS w(cid:239)(cid:200)cznie z metadanymi. Poni(cid:285)ej znajduje si(cid:218) kod (cid:283)ród(cid:239)owy przyk(cid:239)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; } 24 Kup książkęPoleć książkę Rozdzia(cid:225) 1. • Podstawy REST W podklasie tej zosta(cid:239)a nadpisana metoda getClasses() oraz dodano CoffesResource. W pliku WAR podklasy klasy Application mog(cid:200) znajdowa(cid:202) si(cid:218) w katalogach WEB-INF/classes i WEB- -INF/lib. Wdra(cid:285)anie us(cid:239)ug typu RESTful Nast(cid:218)pnym krokiem po utworzeniu zasobu i dodaniu metadanych do podklasy klasy Applica- tion jest utworzenie pliku WAR, który mo(cid:285)na wdro(cid:285)y(cid:202) w ka(cid:285)dym kontenerze serwletów. Kod (cid:283)ród(cid:239)owy opisywanych przyk(cid:239)adów znajduje si(cid:218) w plikach do pobrania z serwera FTP. Dodatkowo mo(cid:285)na w nich znale(cid:283)(cid:202) szczegó(cid:239)owe instrukcje, jak uruchomi(cid:202) te przyk(cid:239)ady. Testowanie us(cid:239)ug typu RESTful Teraz mo(cid:285)emy u(cid:285)y(cid:202) funkcjonalno(cid:258)ci API klienta JAX-RS 2.0 w celu uzyskania dost(cid:218)pu do za- sobów. W tym podrozdziale opisane s(cid:200) nast(cid:218)puj(cid:200)ce tematy: (cid:81) API klienta w JAX-RS 2.0, (cid:81) uzyskiwanie dost(cid:218)pu do zasobów RESTful przy u(cid:285)yciu narz(cid:218)dzia cURL lub rozszerzenia przegl(cid:200)darki internetowej o nazwie Postman. API klienta w JAX-RS 2.0 W JAX-RS 2.0 dodano nowe API klienckie s(cid:239)u(cid:285)(cid:200)ce do uzyskiwania dost(cid:218)pu do zasobów RESTful. Jego punkt pocz(cid:200)tkowy to javax.ws.rs.client.Client. Z tego nowego API mo(cid:285)na korzysta(cid:202) w nast(cid:218)puj(cid:200)cy sposób: Client client = ClientFactory.newClient(); WebTarget target = client.target( http://. . ./coffees/orders ); String response = target.request().get(String.class); Jak wida(cid:202) w tym przyk(cid:239)adzie, domy(cid:258)lny egzemplarz klienta tworzy si(cid:218) przy u(cid:285)yciu metody ClientFactory.newClient(). Za pomoc(cid:200) metody target() zosta(cid:239) utworzony obiekt WebTarget. Z wykorzystaniem obiektów tego typu przygotowuje si(cid:218) (cid:285)(cid:200)danie przez dodanie metody i pa- rametrów zapytania. Zanim nie pojawi(cid:239)y si(cid:218) nowe API, dost(cid:218)p do zasobów REST uzyskiwa(cid:239)o si(cid:218) w nast(cid:218)puj(cid:200)cy sposób: 25 Kup książkęPoleć książkę REST. Najlepsze praktyki i wzorce w j(cid:266)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(cid:239)ad ten wyra(cid:283)nie pokazuje, jak du(cid:285)ego post(cid:218)pu dokonano w API klienckim JAX-RS 2.0 — wyeliminowano konieczno(cid:258)(cid:202) u(cid:285)ywania klasy HttpURLConnection, zamiast której mo(cid:285)na u(cid:285)y- wa(cid:202) API Client. Je(cid:258)li (cid:285)(cid:200)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(cid:200) metody post()wywo(cid:239)uje (cid:285)(cid:200)danie HTTP POST. Metoda post() pobiera jednostk(cid:218) z eg- zemplarza Coffee i okre(cid:258)la typ mediów jako APPLICATION_XML. W kliencie zostaje zarejestrowana implementacja klas MessageBodyReader i MessageBodyWriter. Szerzej na temat tych klas pisz(cid:266) w rozdziale 2. W poni(cid:285)szej tabeli znajduje si(cid:218) zestawienie opisanych do tej pory najwa(cid:285)niejszych klas i adno- tacji JAX-RS. Nazwa javax.ws.rs.Path javax.ws.rs.ApplicationPath javax.ws.rs.Produces javax.ws.rs.Consumes javax.ws.rs.client.Client javax.ws.rs.client.WebTarget Opis Okre(cid:258)la (cid:258)cie(cid:285)k(cid:218) URI, dla której zasób serwuje metod(cid:218). Jest u(cid:285)ywana przez podklas(cid:218) klasy Application jako bazowy URL wszystkich identyfikatorów URI dostarczanych przez zasoby w aplikacji. Definiuje typ mediów, jaki mo(cid:285)e zosta(cid:202) zwrócony przez dany zasób. Definiuje typ mediów przyjmowany przez zasób. Definiuje punkt wej(cid:258)ciowy dla (cid:285)(cid:200)da(cid:241) klienta. Definiuje cel zasobu identyfikowany przez URI. 26 Kup książkęPoleć książkę Rozdzia(cid:225) 1. • Podstawy REST Klienty to ci(cid:218)(cid:285)kie obiekty do obs(cid:239)ugi infrastruktury komunikacyjnej po stronie klienta. Poniewa(cid:285) ich two- rzenie i usuwanie to do(cid:258)(cid:202) czasoch(cid:239)onne operacje, powinno si(cid:218) tworzy(cid:202) jak najmniej tych obiektów. Po- nadto egzemplarz klienta zawsze trzeba poprawnie zamkn(cid:200)(cid:202), aby nie dopu(cid:258)ci(cid:202) do wycieku zasobów. Uzyskiwanie dost(cid:218)pu do zasobów RESTful W tym podrozdziale znajduje si(cid:218) opis ró(cid:285)nych sposobów uzyskiwania dost(cid:218)pu do zasobów REST i testowania ich przez klienty. cURL cURL to popularne narz(cid:218)dzie wiersza polece(cid:241) do testowania API REST. Za jego pomoc(cid:200) u(cid:285)yt- kownik mo(cid:285)e tworzy(cid:202) (cid:285)(cid:200)dania, wysy(cid:239)a(cid:202) je do API i analizowa(cid:202) otrzymane odpowiedzi. Poni(cid:285)ej znajduje si(cid:218) par(cid:218) przyk(cid:239)adowych (cid:285)(cid:200)da(cid:241) curl wykonuj(cid:200)cych podstawowe czynno(cid:258)ci: (cid:191)(cid:200)danie curl Opis curl http://api.foo.com/v1/coffees/1 curl -H foo:bar http://api.foo.com/v1/coffees curl -i http://api.foo.com/v1/coffees/1 curl –X POST -d { name : JanKowalski , username : jkow , phone : 412-344-5644 } http://api.foo.com/v1/users Proste (cid:285)(cid:200)danie GET. (cid:191)(cid:200)danie z dodatkiem nag(cid:239)ówka za pomoc(cid:200) parametru -H. (cid:191)(cid:200)danie z wy(cid:258)wietleniem nag(cid:239)ówków odpowiedzi HTTP za pomoc(cid:200) parametru -i. (cid:191)(cid:200)danie metod(cid:200) POST utworzenia nowego u(cid:285)ytkownika. Cho(cid:202) narz(cid:218)dzie cURL jest bardzo pomocne, ma wiele opcji, które trzeba zapami(cid:218)ta(cid:202). Dlate- go czasami lepszym rozwi(cid:200)zaniem jest u(cid:285)ycie narz(cid:218)dzia przegl(cid:200)darkowego, np. Postman albo Advanced REST client. Postman Postman dla przegl(cid:200)darki Chrome to doskona(cid:239)e narz(cid:218)dzie do testowania i rozwijania API REST. Zawiera przegl(cid:200)dark(cid:218) danych w formatach JSON i XML oraz umo(cid:285)liwia podgl(cid:200)danie (cid:285)(cid:200)da(cid:241) HTTP 1.1, jak równie(cid:285) ich wielokrotne wysy(cid:239)anie i zapisywanie na przysz(cid:239)o(cid:258)(cid:202). Postman dzia(cid:239)a w (cid:258)rodowisku przegl(cid:200)darki internetowej i umo(cid:285)liwia te(cid:285) przegl(cid:200)danie danych cookie. Zalet(cid:200) narz(cid:218)dzia Postman w porównaniu z cURL jest przyjazny interfejs u(cid:285)ytkownika do wpro- wadzania parametrów, dzi(cid:218)ki czemu nie trzeba wpisywa(cid:202) ca(cid:239)ych polece(cid:241) ani skryptów. Ponadto program ten obs(cid:239)uguje ró(cid:285)nego rodzaju metody uwierzytelniania, takie jak uwierzytelnianie podstawowe czy przy u(cid:285)yciu skrótów (tzw. digest access authentication). 27 Kup książkęPoleć książkę REST. Najlepsze praktyki i wzorce w j(cid:266)zyku Java Poni(cid:285)ej znajduje si(cid:218) zrzut ekranu przedstawiaj(cid:200)cy sposób wysy(cid:239)ania zapyta(cid:241) w narz(cid:218)dziu Postman. Na powy(cid:285)szym zrzucie ekranu przedstawiono okno aplikacji Postman. Najprostszym sposo- bem na przetestowanie tego programu jest uruchomienie go w przegl(cid:200)darce Chrome. Nast(cid:218)pnie nale(cid:285)y wybra(cid:202) metod(cid:218) HTTP GET i wpisa(cid:202) adres URL api.postcodes.io/random/ postcodes. (PostCodes to darmowa otwarta us(cid:239)uga, której dzia(cid:239)anie opiera si(cid:218) na danych geo- graficznych). Otrzymasz odpowied(cid:283) JSON podobn(cid:200) do poni(cid:285)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(cid:200) si(cid:218) ró(cid:285)ne zapytania, które zosta(cid:239)y dodane do kolekcji, np. po- branie wszystkich zamówie(cid:241) kawy, pobranie jednego konkretnego zamówienia, utworzenie zamówie(cid:241) itd. na podstawie ró(cid:285)nych przyk(cid:239)adów z tej ksi(cid:200)(cid:285)ki. Mo(cid:285)esz te(cid:285) tworzy(cid:202) w(cid:239)asne ko- lekcje zapyta(cid:241). 28 Kup książkęPoleć książkę Rozdzia(cid:225) 1. • Podstawy REST Pobieranie przyk(cid:239)adów kodu Pliki z przyk(cid:239)adowym kodem (cid:283)ród(cid:239)owym mo(cid:285)na pobra(cid:202) z serwera FTP wydawnictwa Helion, pod adresem ftp://ftp.helion.pl/przyklady/restja.zip. Wi(cid:218)cej informacji na temat narz(cid:218)dzia Postman znajduje si(cid:218) na stronie http://www.getpostman.com/. Inne narz(cid:218)dzia Oto par(cid:218) innych narz(cid:218)dzi, które równie(cid:285) mog(cid:200) by(cid:202) przydatne w pracy z zasobami REST. Advanced REST client Advanced REST client to kolejne rozszerzenie przegl(cid:200)darki Chrome oparte na Google Web- Toolkit i s(cid:239)u(cid:285)(cid:200)ce do testowania oraz tworzenia API REST. JSONLint JSONLint to proste internetowe narz(cid:218)dzie do sprawdzania poprawno(cid:258)ci danych w formacie JSON. Gdy wysy(cid:239)a si(cid:218) dane w tym formacie, dobrze jest sprawdzi(cid:202), czy s(cid:200) sformatowane zgod- nie ze specyfikacj(cid:200). Mo(cid:285)na to zrobi(cid:202) w(cid:239)a(cid:258)nie za pomoc(cid:200) narz(cid:218)dzia JSONLint. Wi(cid:218)cej informa- cji na jego temat znajduje si(cid:218) na stronie http://jsonlint.com/. Najlepsze praktyki projektowania zasobów W tym podrozdziale znajduje si(cid:218) opis niektórych najlepszych praktyk projektowania zasobów RESTful: (cid:81) Programista API powinien u(cid:285)ywa(cid:202) rzeczowników, aby u(cid:239)atwi(cid:202) u(cid:285)ytkownikowi poruszanie si(cid:218) po zasobach, a czasowników tylko jako metod HTTP. Na przyk(cid:239)ad URI /user/1234/books jest lepszy ni(cid:285) /user/1234/getBook. (cid:81) Do identyfikacji podzasobów u(cid:285)ywaj asocjacji. Na przyk(cid:239)ad aby pobra(cid:202) autorów ksi(cid:200)(cid:285)ki 5678 dla u(cid:285)ytkownika 1234, powinno si(cid:218) u(cid:285)y(cid:202) URI /user/1234/books/ 5678/authors. (cid:81) Do pobierania specyficznych wariacji u(cid:285)ywaj parametrów zapyta(cid:241). Na przyk(cid:239)ad aby pobra(cid:202) wszystkie ksi(cid:200)(cid:285)ki maj(cid:200)ce 10 recenzji, u(cid:285)yj URI /user/1234/ books?reviews_counts=10. (cid:81) W ramach parametrów zapyta(cid:241) w razie mo(cid:285)liwo(cid:258)ci zezwalaj na cz(cid:218)(cid:258)ciowe odpowiedzi. Przyk(cid:239)adem mo(cid:285)e by(cid:202) pobranie tylko nazwy i wieku u(cid:285)ytkownika. Klient mo(cid:285)e wys(cid:239)a(cid:202) w URI parametr zapytania ?fields zawieraj(cid:200)cy list(cid:218) pól, które chce otrzyma(cid:202) od serwera, np. /users/1234?fields=name,age. 29 Kup książkęPoleć książkę REST. Najlepsze praktyki i wzorce w j(cid:266)zyku Java (cid:81) Zdefiniuj domy(cid:258)lny format odpowiedzi na wypadek, gdyby klient nie poda(cid:239), jaki format go interesuje. Wi(cid:218)kszo(cid:258)(cid:202) programistów jako domy(cid:258)lnego formatu u(cid:285)ywa JSON. (cid:81) W nazwach atrybutów stosuj notacj(cid:218)Wielb(cid:239)(cid:200)dzi(cid:200) lub ze znakami podkre(cid:258)lenia _. (cid:81) Dla kolekcji zapewnij standardowe API licz(cid:200)ce, np. users/1234/books/count, aby klient móg(cid:239) sprawdzi(cid:202), ilu obiektów mo(cid:285)e si(cid:218) spodziewa(cid:202) w odpowiedzi. B(cid:218)dzie to te(cid:285) pomocne dla klientów u(cid:285)ywaj(cid:200)cych stronicowania. Szerzej na temat stronicowania pisz(cid:218) w rozdziale 5. (cid:81) Zapewnij opcj(cid:218) eleganckiego drukowania — users/1234?pretty_print. Ponadto nie powinno si(cid:218) buforowa(cid:202) zapyta(cid:241) z parametrem drukowania. (cid:81) Staraj si(cid:218) minimalizowa(cid:202) komunikacj(cid:218) przez dostarczenie jak najpe(cid:239)niejszych informacji w pierwszej odpowiedzi. Chodzi o to, (cid:285)e je(cid:258)li serwer nie dostarczy wystarczaj(cid:200)cej ilo(cid:258)ci danych w odpowiedzi, klient b(cid:218)dzie musia(cid:239) wys(cid:239)a(cid:202) kolejne (cid:285)(cid:200)dania, aby zdoby(cid:202) potrzebne mu informacje. W ten sposób marnuje si(cid:218) zasoby i wyczerpuje limit (cid:285)(cid:200)da(cid:241) klienta. Szerzej na temat ograniczania liczby (cid:285)(cid:200)da(cid:241) klienta pisz(cid:218) w rozdziale 5. Zalecana lektura (cid:81) RFC 2616: http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html. (cid:81) Model dojrza(cid:239)o(cid:258)ci Richardsona: http://www.crummy.com/writing/speaking/ 2008-QCon/act3.html. (cid:81) Implementacja JAX-RS Jersey: https://jersey.java.net/. (cid:81) InspectB.in: http://inspectb.in/. (cid:81) Postman: http://www.getpostman.com/. (cid:81) Advanced REST Client: https://code.google.com/p/chrome-rest-client/. Podsumowanie W tym rozdziale przedstawi(cid:239)am podstawowe za(cid:239)o(cid:285)enia technologii REST, opisa(cid:239)am API CRUD oraz pokaza(cid:239)am, jak projektowa(cid:202) zasoby RESTful. W przyk(cid:239)adach u(cid:285)yte zosta(cid:239)y adnotacje JAX- -RS 2.0, za pomoc(cid:200) których mo(cid:285)na reprezentowa(cid:202) metody HTTP, i API klienckie, przy u(cid:285)yciu których mo(cid:285)na odnosi(cid:202) si(cid:218) do zasobów. Ponadto zrobi(cid:239)am przegl(cid:200)d najlepszych praktyk pro- jektowania us(cid:239)ug typu RESTful. W nast(cid:218)pnym rozdziale znajduje si(cid:218) rozszerzenie tych wiadomo(cid:258)ci. Bardziej szczegó(cid:239)owo po- znasz zasady negocjowania tre(cid:258)ci, dostawców jednostek w JAX-RS 2.0, techniki obs(cid:239)ugi b(cid:239)(cid:218)dów, sposoby kontrolowania wersji oraz kody odpowiedzi REST. Ponadto dowiesz si(cid:218), w jaki spo- sób serwer mo(cid:285)e wysy(cid:239)a(cid:202) do klienta odpowiedzi przy u(cid:285)yciu strumieniowania i kawa(cid:239)kowania. 30 Kup książkęPoleć książkę Skorowidz architektura mikrous(cid:239)ugowa, 108 niezale(cid:285)no(cid:258)(cid:202), 109 podzia(cid:239) funkcjonalno(cid:258)ci, 109 prostota, 108 skalowalno(cid:258)(cid:202), 109 wyodr(cid:218)bnienie problemów, 108 architektura REST, 59 asynchroniczne obs(cid:239)ugiwanie zada(cid:241), 74 przetwarzanie, 70 atrybut href, 93 method, 94 rel, 94 autoryzacja, 54 B Bean Validation, 49 bezpiecze(cid:241)stwo, 45 bezpiecze(cid:241)stwo metod, 18 bezstanowo(cid:258)(cid:202), 16 biblioteka Log4j, 47 b(cid:239)(cid:200)d 406, 34 415, 34 420, 87 429, 80, 85 BOSH, 107 buforowanie, 64, 69, 86 buforowanie na serwerze, 70 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(cid:200)ce na bie(cid:285)(cid:200)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 Kup książkęPoleć książkę REST. Najlepsze praktyki i wzorce w j(cid:266)zyku Java C CRUD, create, read, update, delete, 19 czas odpowiedzi, 64 (cid:285)ycia tokenu, 58 czasowniki, 113 czasowniki HTTP, 17, 21 D dane JSON, 39 osobowe, 48 dodanie metadanych, 25 dokumentowanie us(cid:239)ug, 95 dostawca to(cid:285)samo(cid:258)ci, 53 us(cid:239)ug, 53, 56 jednostek, 35 dost(cid:218)p do zasobów REST, 25, 27 dyrektywa QoS, 100 dyrektywy nag(cid:239)ówka Cache-Control, 65 dzia(cid:239)anie gniazd sieciowych, 105 E eksplorator API Graph, 115 elementy architektury REST, 59 F filtr ograniczaj(cid:200)cy (cid:285)(cid:200)dania, 82 rejestruj(cid:200)cy, 46 format JSON, 39 funkcje interfejsu EventSource, 102 funkcjonalno(cid:258)ci gniazd sieciowych, 106 G gniazdo sieciowe, WebSocket, 104 grant autoryzacji, 57 H HATEOAS, 18, 92, 93 122 I idempotentno(cid:258)(cid:202) 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 J 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ę 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(cid:258)ci, 74 komunikacja na bie(cid:285)(cid:200)co, 106 L liczba (cid:285)(cid:200)da(cid:241), 80 lista wariantów reprezentacji, 34 logowanie pojedyncze, SSO, 53 lokalizacja, 91 M maper wyj(cid:200)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 (cid:285)(cid:200)danie idempotentne, 18 uwierzytelniania, 27 mikrous(cid:239)ugi, 107–110 model dojrza(cid:239)o(cid:258)ci Richardsona, 16 PubSubHubbub, 99 strumieniowania, 100 Skorowidz N nag(cid:239)ó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(cid:239)ówki buforowania silne, 64 s(cid:239)abe, 64 narz(cid:218)dzie Advanced REST client, 29 cURL, 27 JSONLint, 29 Postman, 27, 29 negocjacja tre(cid:258)ci, 32 poprzez adres URL, 35 poprzez nag(cid:239)ówki HTTP, 32 niezawodno(cid:258)(cid:202), 16 numer wersji, 41 w nag(cid:239)ó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(cid:239)uga b(cid:239)(cid:218)dów, 51, 113, 116, 119 kodów odpowiedzi, 50 wyj(cid:200)tków, 50 odpowiedzi REST, 31 ograniczanie liczby (cid:285)(cid:200)da(cid:241), 80–82, 114, 117 okre(cid:258)lanie wersji, 40 wersji API, 41 OpenID Connect, 59 operacje asynchroniczne, 70 d(cid:239)ugotrwa(cid:239)e, 70 123 Kup książkęPoleć książkę REST. Najlepsze praktyki i wzorce w j(cid:266)zyku Java P R pliki WAR/EAR, 108 POJO, 39 poprawno(cid:258)(cid:202) us(cid:239)ug REST, 49 portal Facebook, 114 portal GitHub, 111 czynno(cid:258)ci zasobów, 116 obs(cid:239)uga b(cid:239)(cid:218)dów, 116 ograniczanie liczby (cid:285)(cid:200)da(cid:241), 117 wersjonowanie, 116 akcje zasobów, 113 obs(cid:239)uga b(cid:239)(cid:218)dów, 113 ograniczanie liczby (cid:285)(cid:200)da(cid:241), 114 pobieranie informacji, 112 wersjonowanie, 113 portal Twitter, 117 dzia(cid:239)ania na zasobach, 118 obs(cid:239)uga b(cid:239)(cid:218)dów, 119 wersjonowanie, 119 POX, Plain Old XML, 17 procedura bookavailable, 102 newbookadded, 102 procedury nas(cid:239)uchowe, 102 proces asynchronicznego przetwarzania, 71 autoryzacji, 55 projektowanie wydajnych rozwi(cid:200)za(cid:241), 63 zasobów, 29, 31 protokó(cid:239) 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 124 rejestrowanie informacji, 46, 47 tre(cid:258)ci, 48 (cid:285)(cid:200)da(cid:241), 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(cid:285)ytkownik, 56 rozszerzalno(cid:258)(cid:202), 94 S SAML, Security Assertion Markup Language, 53 serializacja zasobów, 35 serwer, 100 skalowalno(cid:258)(cid:202), 16 SOAP, Simple Object Access Protocol, 15 sondowanie, polling, 98 sondowanie spowolnione, 107 sprawdzanie poprawno(cid:258)ci danych, 29 us(cid:239)ug REST, 49 SSE, Server-Send Events, 100 SSL, 58 SSO, Single Sign-On, 53 sta(cid:239)a REQ_LIMIT, 82 status COMPLETED, 75 PROCESSING, 75 statyczna negocjacja tre(cid:258)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ę T tablica JSONArray, 90 technologia BOSH, 107 OpenID Connect, 59 REST, 11, 97 SOA, 15 termin wyga(cid:258)ni(cid:218)cia, 74 testowanie us(cid:239)ug, 95 typu RESTful, 25 token, 54 dost(cid:218)pu, 57 od(cid:258)wie(cid:285)ania, 57, 58 tworzenie API REST, 29 asynchronicznego zasobu, 72 listy wariantów reprezentacji, 34 zasobu RESTful, 23 typ MIME, 34 typy nag(cid:239)ówków buforowania, 64 znaczników ETag, 68 U uchwyt sieciowy, WebHook, 103 uk(cid:239)ad projektu, 81, 90 unikanie sondowania, 86 us(cid:239)uga GitHub, 104 IPN, 104 us(cid:239)ugi typu RESTful, 19 utrata po(cid:239)(cid:200)czenia, 101 uwierzytelnianie, 27, 53 uzgodnienie, handshake, 107 u(cid:285)ycie gniazd sieciowych, 106 W wdra(cid:285)anie us(cid:239)ug typu RESTful, 25 wersjonowanie API, 40 weryfikacja poprawno(cid:258)ci danych, 50 w(cid:218)ze(cid:239) komunikacyjny, 99 wiadomo(cid:258)(cid:202) SSE, 101 SSE z identyfikatorem, 101 Skorowidz wi(cid:200)zanie identyfikatora ze zdarzeniem, 101 nazw ze zdarzeniami, 101 widoczno(cid:258)(cid:202), 16 WSDL, Web Service Description Language, 15 wyj(cid:200)tek, 50 CoffeeNotFoundException, 51 wykrywalno(cid:258)(cid:202), 45 wysy(cid:239)anie nag(cid:239)ówka Accept, 42 numeru wersji, 41 wzorce REST, 42 XMPP, 106 X Z zaciemnianie danych poufnych, 47 zasady zasoby buforowania, 64 projektowania, 79 asynchroniczne, 73 REST, 17 RESTful, 19, 22 zdalne wywo(cid:239)ywanie procedur, 17 zdarzenia SSE, 100–103, 107 uchwytów sieciowych, 103 ziarno JAXB, 39 znaczniki ETag, 67, 68 (cid:285)(cid:200)dania (cid:285)(cid:200)danie curl, 27, 85 w p(cid:218)tlach, 86 DELETE, 21 GET, 21 HEAD, 22 OAuth, 55 PATCH, 74, 76 POST, 21, 26 PUT, 21 Upgrade, 104 (cid:191) 125 Kup książkęPoleć książkę REST. Najlepsze praktyki i wzorce w j(cid:266)zyku Java 126 Kup książkęPoleć książkę
Pobierz darmowy fragment (pdf)

Gdzie kupić całą publikację:

REST. Najlepsze praktyki i wzorce w języku Java
Autor:

Opinie na temat publikacji:


Inne popularne pozycje z tej kategorii:


Czytaj również:


Prowadzisz stronę lub blog? Wstaw link do fragmentu tej książki i współpracuj z Cyfroteką: