Návrh a implementace RESTových rozhraní

Transkript

1 Masarykova univerzita Fakulta informatiky Návrh a implementace RESTových rozhraní Bakalářská práce Tomáš Schmidl Brno, jaro 2016

2

3 Prohlášení Prohlašuji, že tato bakalářská práce je mým původním autorským dílem, které jsem vypracoval samostatně. Všechny zdroje, prameny a literaturu, které jsem při vypracování používal nebo z nich čerpal, v práci řádně cituji s uvedením úplného odkazu na příslušný zdroj. Tomáš Schmidl Vedoucí práce: doc. RNDr. Petr Sojka, Ph.D. i

4

5 Poděkování Chtěl bych poděkovat vedoucímu své práce, doc. RNDr. Petru Sojkovi, Ph.D. za pomoc při ujasnění cílů práce samotné, za čas, který mi věnoval a za cenné rady a zkušenosti předané při ladění formální stránky práce. Dále bych chtěl poděkovat firmě CleverAnalytics za čas a prostor poskytnutý mi pro psaní práce, a především Ing. Jiřímu Žaloudkovi za jeho odborné konzultace, a za neustávající snahu udělat ze mě lepšího programátora. iii

6 Shrnutí Tato bakalářská práce se zábývá návrhem a implementací webových rozhraní založených na REST architektuře. V úvodu práce se čtenář seznámí s principy REST architektury a požadavky, které klademe na systémy, jež tento druh rozhraní implementují. Jsou mu nastíněny způsoby, jimiž se dá přistupovat k návrhu těchto rozhraní. Náplní analytické části je rozbor a porovnání dostupných frameworků v jazyce Java. Praktická část se pak věnuje implementaci rozhraní, které je součástí backendu CleverAnalytics, cloudové platformy pro lokační analýzu. iv

7 Klíčová slova Java, REST, API, framework, JSON, Spring, RESTEasy, Jersey, Restlet, Dropwizard v

8

9 Obsah Úvod REST architektura Principy definující REST architekturu Model klient-server Přístup ke zdrojům a jejich reprezentace Bezstavovost Uniformní rozhraní, HATEOAS Správa mezipaměti Rozdělení do vrstev Komunikace skrze RESTové rozhraní Protokol HTTP HTTP metody HTTP hlavičky HTTP status kódy Příklad komunikace Nefunkční požadavky kladené na RESTová rozhraní Výkon Škálovatelnost Jednoduchost Modifikovatelnost Přenositelnost Spolehlivost Návrh RESTových rozhraní Stanovení funkčních požadavků Datové popisovací jazyky XML Schema JSON Schema CRUD Koncové body Popisovací jazyky rozhraní OpenAPI Specification RAML API Blueprint Analýza frameworků Spring framework vii

10 5.2 RESTEasy Jersey Restlet Dropwizard Shrnutí Implementace RESTového rozhraní Funkční požadavky Výběr technologií Vrstva controlleru Objektový datový model Model-View-Controller Stránkování zdrojů Verzování zdrojů Servisní vrstva Mapování mezi datovými modely JPA repozitář Perzistentní vrstva Relační datový model PostgreSQL typ json ORM Testy Unit testy Integrační testy Zátěžové testy Shrnutí praktické části Závěr Literatura Rejstřík A Appendix A.1 Ukázky kódu A.2 Obrázky A.3 Návod ke spuštění a používání aplikace viii

11 Úvod Příchod webu způsobil převrat ve způsobu, kterým sdílíme informace. V průběhu několika desítek let se stal prostředkem pro tvorbu a využití nespočtu druhů aplikací. Webové aplikace jsou dostupné každému s připojením k internetu. Nevyžadují instalaci, nejsou hardwarově náročné a k použití většiny z nich stačí internetový prohlížeč. Každá webová aplikace je ve své podstatě webovou službou programem spuštěným někde na serveru. Webové aplikační rozhraní Web API je prostředkem k vnější komunikaci s webovou službou. Definuje množinu metod, které umožňují získávat od služby požadované zdroje, či měnit její vnitřní stav. Tato práce se zabývá návrhem a implementací webových rozhraní stavěných na REST architektuře. [1] REST architektura nepatří k nejmladším, ale v posledních letech se těší stále větší popularitě [2] a stala se de facto standardem pro tvorbu webových rozhraní. První kapitola se zaměřuje na REST jako koncept a definuje základní charakteristiky, které musí rozhraní splňovat, aby se dalo za RESTové považovat. Komunikace specifická pro REST architekturu prostřednictvím tzv. hypermédií, je popsána v úvodní kapitole. Nefunkčním požadavkům, které klademe na aplikace využívající RES- Tová rozhraní je věnována kapitola 3. Formální přístup k návrhu a popisovací jazyky rozhraní jsou představeny ve čtvrté kapitole. V praktické části se pak věnuji analýze dostupných frameworků pro jazyk Java a kapitola 6 je věnována implementaci samotné. 1

12 1 REST architektura REST (REpresentation State Transfer) je architektura rozhraní používaná v distribuovaných systémech, dnes zejména u webových služeb. REST architektura je nezávislá na konkrétní implementaci, či syntaxi komunikačního protokolu na kterém funguje. Definuje konkrétní úlohy jednotlivých komponent, pravidla jejich komunikace a interpretaci datových zdrojů, se kterými pracuje. Architekturu jako takovou poprvé popsal Roy Fielding ve své disertační práci Architectural Styles and the Design of Network-based Software Architectures. [3] Fielding prezentuje dva přístupy, pomocí kterých lze nahlížet na návrh architektury systému, ať už se jedná o softwarovou aplikaci, nebo budovu. První možností je začít od nuly. Architekt pak na základě svých znalostí a osvědčených postupů dojde k výsledku, jež splňuje prvotní požadavky. Druhou možností je nadefinovat si systém jako fungující celek a na něj inkrementálně aplikovat podmínky a omezení, které by měl výsledný návrh splňovat. Zatímco první přístup podporuje tvořivost architekta a dává mu větší volnost návrhu, druhý klade důraz na dodržení stanovených omezení a lepší porozumění systému jako celku. REST architektura byla navržena za pomoci druhého přístupu. Podléhá tedy několika principům, jež budou popsány ve zbytku kapitoly. 1.1 Principy definující REST architekturu Za RESTová rozhraní 1 můžeme považovat taková rozhraní, která splňují následující podmínky: Operují na modelu klient-server. Jsou bezstavové. Využívají uniformní přístup ke zdrojům. 1. V angličtině se pro RESTová rozhraní používá termín RESTful. Považujme tedy REST za architekturu a termín RESTful RESTový za označení pro webové služby, které REST architekturu implementují. 2

13 1. REST architektura Podporují správu mezipaměti. Jsou vrstvená Model klient-server Model klient-server je jednou z nejpoužívanějších architektur u webově založených aplikací. [3, sekce 3.4.1] Na serveru je spuštěna jedna nebo více služeb, které naslouchají příchozím požadavkům. Klient požadující po serveru určitou službu pošle požadavek skrze dané rozhraní. Server požadavek zpracuje či odmítne, a klientovi vrátí příslušnou odpověď, jak vidno na obrázku 1.1. Obrázek 1.1: Klient-server model Klíčovým konceptem je oddělení zodpovědností (separation of concerns). Jednotlivé komponenty modelu by měly být navrženy tak, aby se jejich funkcionality překrývaly co nejméně. Správné oddělení zodpovědností je důležité pro budoucí škálovatelnost celého systému. Služba na serveru by měla zpracovávat příchozí požadavky, spravovat zdroje, jejich uložení (např. v databázi) a reprezentaci. Klient má na starosti přijímání a zpracování odpovědí, a kompletní funkcionalitu uživatelského rozhraní. Díky tomuto oddělení může vývoj jednotlivých komponent probíhat nezávisle na sobě za předpokladu, že se rozhraní nezmění. Dobrý návrh rozhraní je tedy naprosto zásadní pro další život systému. Pozdější zásahy do rozhraní si totiž vynucují změny jak na serveru, tak na klientovi, a to podstatně ztěžuje práci se systémem Přístup ke zdrojům a jejich reprezentace REST architektura je na rozdíl od známějších XML-RPC či SOAP, orientována datově, nikoli procedurálně. Zdroje jsou tedy fundamentálním 3

14 1. REST architektura základem každého REST API. Z pohledu klienta může být zdrojem vše, s čím tento klient přijde do styku, aby dosáhl požadovaného cíle. Může se zdát, že mnoho zdrojů ze skutečného světa je nemožné převést na jejich webovou podobu. Avšak prosté vystavení informací o tomto zdroji, či popis jak jej získat, z něj dělá dosažitelný webový zdroj. Abychom mohli se zdrojem jakkoliv manipulovat, musíme být schopni jej identifikovat. K tomuto účelu slouží URI (Uniform Resource Identifier). URI jednoznačně identifikuje zdroj a činí ho adresovatelným. Tento identifikátor nám umožňuje se zdrojem manipulovat na síti. Mezi zdroji a jejich URI platí 1:n kardinalita. Tj. URI vždy identifikuje právě jeden zdroj, avšak jeden zdroj může být popsán více URI. Na počet možných URI se neklade žádný limit, tudíž na jeden zdroj může odkazovat nekonečné množství URI. V případě google.com, se jedná o 3 různé URI, které však identifikují jediný zdroj domovskou stránku společnosti Google. Syntaxe URI má tvar <schéma>:<schématu-specifická-struktura>. V případě URI rozumíme https jako definici schématu, na základě které se za pomoci DNS vyhodnotí jméno hostitelské domény example.org, jejíž vnitřní služby namapují zbytek URI /people/john na konkrétní zdroj. [1, str. 7] Kromě identifikátoru URI jsou k dispozici i: URL (Uniform Resource Locator)» Identifikátor URL navíc specifikuje, jakým způsobem má klient přistupovat k danému zdroji. Pokud URL obsahuje prefix http, víme, že ke zdroji můžeme přistoupit za pomoci protokolu HTTP. Tento pojem je už zastaralý, jelikož ne všechny URI musí obsahovat informaci jak zdroj zpracovat. Do historie webu se však identifikátor URL vžil více než URI, a tak se stále hojně používá. IRI (International Resource Identifier)» Rozšíření URI, které dovoluje použití mezinárodních znakových sad. 4

15 URN (Uniform Resource Name) 1. REST architektura» URI, jehož schématem je urn, a jehož zbytek spadá do určitého jmenného prostoru. Např. knihu jednoznačně identifikuje pomocí ISBN: urn:isbn: Každý zdroj tedy musí mít alespoň jeden identifikátor. Tento identifikátor dále může mít jednu a více reprezentací. Reprezentace je transformace, nebo pohled na určitý zdroj v čase. Reprezentace zdroje může nabývat různého množství formátů, jako např. XML, XHTML, JSON, Atom, prostý text, či multimédia jako JPG, nebo MP4. Mějme tedy zdroj, který bychom v běžném životě popsali jako Karel IV., český král a císař římský z rodu Lucemburků. Zdroj je dostupný na URI Požadavkem na tuto adresu získáme zdroj v příslušné reprezentaci. { } Listing 1.1: JSON reprezentace zdroje "king": { "name": "Charles IV", "house": "House of Luxembourg", "born": { "place": "Prague", "year": 1316 } "titles": [ "King of Bohemia", "Holy Roman Emperor" ] } 5

16 1. REST architektura Listing 1.2: XML reprezentace zdroje <king> <name>charles IV</name> <house>house of Luxembourg</house> <birth place="prague">1316</birth> <titles> <title>king of Bohemia</title> <title>holy Roman Emperor</title> </titles> </king> Separace zdroje a jeho reprezentace dodržuje volné propojení komponent (loose coupling), jeden ze základních principů webu. Přístup k určitému zdroji probíhá vždy skrze jeho reprezentaci. Webová služba dokáže daný zdroj vystavit v požadované reprezentaci na základě klientova požadavku. Reprezentace zdroje může být specifikována v URI ( tento způsob je ale zastaralý a ne zcela vhodný pro použití v RESTových rozhraních. Sofistikovanějším způsobem je použití HTTP hlavičky Accept, viz kapitola na straně 10. [1] Bezstavovost Dalším omezením, které na náš systém aplikujeme, je bezstavovost. Komunikace mezi klientem a serverem v RESTovém rozhraní musí být bezstavová. V průběhu komunikace nesmí být na serveru uchováván žádný klientský kontext. Každý požadavek, který klient na server pošle, musí tedy obsahovat dostatek informací, aby byl server schopen tomuto požadavku porozumět a zpracovat ho. [3, sekce 5.1] Server může požadavek předat jiné službě, například té, která se stará o uchování (zperzistování) dat do databáze. Stav komunikace může být uchován, ale pouze na straně klienta. Náš systém bude fungovat na protokolu HTTP, jež je klasickým příkladem bezstavového protokolu [4], na rozdíl např. od protokolu FTP, kde server naváže interaktivní spojení s klientem a před zahájením komunikace si uchová informace o klientově pracovním adresáři, nebo typu přenosu. 6

17 1. REST architektura Uniformní rozhraní, HATEOAS Uniformní rozhraní je základním principem REST architektury, kterým se odlišuje od ostatních síťových aplikačních architektur. [3, sekce 5.1] Pokud je u jednotlivých komponent kladen důraz na všeobecnost jejich rozhraní, celková architektura systému je zjednodušena a interakce mezi komponentami jsou snáze viditelné. Jednotlivé implementace pak mohou být oddělené od služeb které poskytují, což umožňuje vývoj komponent nezávislý na změnách v ostatních částech systému. Tento princip také vzešel z disertační práce Roye Fieldinga, a později se pro něj ujalo označení HATEOAS Hypermedia as the Engine of Application State (Hypermédia jako aplikační stav). Hypermédii zde rozumíme rozšíření hypertextu tj. textu zobrazeného na obrazovce počítače, jež obsahuje odkazy (hyperlinky), které můžou odkazovat na další texty. Hypermédia mohou kromě prostého textu obsahovat i grafiku, či audio nebo video. Jako hypermédium můžeme označit např. internet. Klient tedy kromě URI a základního porozumění hypermédiím nepotřebuje pro komunikaci s webovou službou skrze RESTové rozhraní žádné další informace. Komunikaci se službou započne skrze vstupní URI a veškerá následující komunikace se odehrává na základě odpovědí služby v podobě hypermédií, jež jsou reprezentacemi zdrojů uložených na serveru. [5] Správa mezipaměti Podpora správy mezipaměti, neboli caching umožňuje zvýšit efektivitu komunikace mezi klientem a serverem. Tato podmínka říká, že odpověď serveru by měla implicitně či explicitně určovat, zda je kešovatelná či ne. Pokud odpověď kešovatelná je, klientova mezipaměť je schopna tuto odpověď znovu využít pro pozdější, ekvivalentní požadavky. Správným využitím kešování dokážeme částečně, či úplně eliminovat některé interakce, a tím zlepšit jeho efektivitu a škálovatelnost. Snížení latence mezi požadavky je také pozitivně vnímáno uživateli. Kompromisem zde však je fakt, že využití mezipaměti může vést ke snížení spolehlivosti, pokud se data v mezipaměti znatelně liší od dat, která by klient získal přímým požadavkem na server. [3, sekce 5.1] 7

18 1. REST architektura Rozdělení do vrstev Za účelem dalšího vylepšení chování REST architektury na distribuovaných systémech o velikosti internetu, zavádíme podmínku vrstvení. Ačkoliv model klient-server už vynucuje jistou formu rozdělení funkcionality, přidání dalších vrstev umožňuje např. oddělit nové komponenty od zastaralých, zjednodušit komponenty přesunutím jejich málo využívané funkcionality do sdílených prostředníků, či ulehčit jednotlivým komponentám práci při velkém zatížení. Nevýhodou většího vrstvení je zvýšení provozních nákladů a zvýšení latencí mezi požadavky. Webově založené služby toto mohou kompenzovat použitím sdílených mezipamětí, zejména jejich vhodným umístěním na hranice organizačních domén. Vrstvy také mohou být využity k vynucování bezpečnostních politik. Komunikace skrze RESTové rozhraní je sice dvoucestná, ale probíhá na základě hypermédií, která jsou každé komponentě viditelná a která může každá komponenta aktivně měnit. Kombinace vrstvení a uniformního rozhraní tak v určitých případech přibližuje REST architekturu návrhovému vzoru roura. [3, sekce 5.1] 8

19 2 Komunikace skrze RESTové rozhraní Vložme si tedy dříve definované podmínky jako uniformní rozhraní či zdroje do kontextu rozhraní fungujícího na protokolu HTTP. HTTP je pouze jedním z mnoha komunikačních protokolů a REST architektura není pevně definována nad ním. HTTP je však hlavní komunikační protokol internetu, a protože navrhujeme webovou službu, budeme pracovat s ním. 2.1 Protokol HTTP HTTP metody HTTP definuje metody označující, jaký druh akce se má nad daným zdrojem provést. Tato relativně malá a dobře nadefinovaná množina metod s jasnou sémantikou splňuje požadavky většiny distribuovaných systémů, a tudíž splňuje i definici uniformního rozhraní. HTTP metody můžeme rozdělit na bezpečné (GET, HEAD, OPTIONS, TRACE, CONNECT), a metody měnící stav serveru (POST, PUT, DELETE, PATCH). Z hlediska RESTových rozhraní nás zajímá zejména druhá kategorie. HTTP metody také mohou obsahovat tělo, mohou být kešovatelné či idempotentní, shrnutí jejich vlastností je dostupné v tabulce 2.1 na následující straně. [6] GET POST PUT» Požadavek na vrácení reprezentace specifikovaného zdroje. Metoda GET načte data a neměla by mít žádný jiný efekt.» Požadavek na akceptování nové entity vložené v těle požadavku, její uložení v podobě nového zdroje a přidělení URI.» Požadavek na nahrazení již existující entity uložené pod danou URI. 9

20 2. Komunikace skrze RESTové rozhraní PATCH» Požadavek na nahrazení části již existující entity uložené pod danou URI. DELETE» Požadavek na smazání specifikované entity. Metoda Tělo požadavku Tělo odpovědi Bezpečná Idempotentní a Kešovatelná GET ne ano ano ano ano HEAD ne ne ano ano ano PUT ano ano ne ano ne DELETE ne ano ne ano ne OPTIONS ne ano ano ano ne TRACE ne ano ano ano ne POST ano ano ne ne ano b CONNECT ano ano ne ne ne PATCH ano ano ne ne ano a. Metoda je idempotentní, pokud jejím opakovaným voláním získáme stejný výstup, jako jejím prvním voláním. b. Kešování odpovědi POST metody je výjimečné, používá se spíše status kód 303 See Other přesměrování klienta na zdroj, který kešovatelný je. Obrázek 2.1: Shrnutí vlastností HTTP metod [7] HTTP hlavičky HTTP požadavky a odpovědi mohou být opatřeny hlavičkami. Ty obsahují doplňující informace o tom, jak dále má služba či klient nakládat se zdrojem. Hlaviček existuje velké množství a dělí se na dvě hlavní kategorie hlavičky požadavků a hlavičky odpovědí. [6] Je možné nadefinovat si libovolné vlastní hlavičky, ty se typicky označují prefixem X-. Hlavičky, které se často používají v RESTových rozhraních jsou popsány v tabulkách 2.2 a 2.3 na následující straně. 10

21 2. Komunikace skrze RESTové rozhraní Hlavička Popis Příklad použití Accept Typ obsahu akceptovatelný v odpovědi Accept: application/json Authorization Údaje pro HTTP autorizaci Authorization: c3rvcm1wyxrolmn Cache-Control Direktivy pro nastavení mezipaměti Cache-Control: no-cache Connection Nastavení udržení připojení Connection: keep-alive Cookie HTTP cookie a poslaná dříve v Set-Cookie Cookie: Background=blue Content-Type Typ obsahu v těle požadavku Content-Type: application/xml Host Hostitelské jméno serveru Host: example.org If-Match Podmíněný požadavek, provede se při shodě If-Match: W/"1" a. HTTP cookies byly poprvé nadefinovány v RFC Slouží k označení malého množství dat odeslaného serverem, které si klient (typicky prohlížeč) uloží pro pozdější použití. Obsahuje obvykle uživatelskou konfiguraci, nebo příznak pro zapamatování uživatelova přihlášení. [8] Obrázek 2.2: Hlavičky požadavků Hlavička Popis Příklad použití Cache-Control Direktivy pro nastavení mezipaměti Cache-Control: max-age=3600 Content-Length Velikost těla odpovědi v bytech Content-Length: 245 Date Datum a čas odeslání zprávy Date: Sat, 30 Apr :36:40 GMT ETag Identifikátor verze zdroje ETag: "2" Last-Modified Datum a čas poslední úpravy zdroje Last-Modified: Sun, 31 Apr :29:17 GMT Set-Cookie Nastavení HTTP cookie Set-Cookie: Login=john1987 Server Název serveru Server: Apache-Coyote/1.1 Transfer-Encoding Forma kódování použitá k přenosu zprávy Obrázek 2.3: Hlavičky odpovědí Transfer-Encoding: chunked 11

22 2. Komunikace skrze RESTové rozhraní HTTP status kódy Jako odpovědi na tyto metody HTTP definuje status kódy (response codes). HTTP kódy mají syntax diskrétního třímístného čísla a popisu. I ty můžeme rozdělit do několika kategorií: [9] 1xx informační, 2xx úspěšné, 3xx přesměrování, 4xx chyba na straně klienta, 5xx chyba na serveru. Mezi nejčastěji používané status kódy patří: 200 OK» Požadavek byl úspěšný. Odpověď se liší na základě metody požadavku. GET obvykle vrací konkrétní zdroj, POST může vracet entitu popisující výsledek uložení nového zdroje. 201 Created» Uložení či úprava nového zdroje byla úspěšná. Tato odpověď vystihuje úspěšné provedení metod POST a PUT. 204 No Content» Server úspěšně vykonal požadavek, avšak nevrací žádné tělo odpovědi. Může obsahovat doplňující HTTP hlavičky. Typická odpověď na úspěšné provedení metody DELETE. 304 Not Modified» Indikuje, že zdroj nebyl od posledního požadavku nijak změněn. 400 Bad Request» Server nedokázal porozumět danému požadavku kvůli chybě v jeho syntaxi. 12

23 401 Unauthorized 2. Komunikace skrze RESTové rozhraní» Server k dokončení požadavku vyžaduje autentizaci klienta. Požadavek musí obsahovat hlavičku Authenticate s validním obsahem. 403 Forbidden» Server porozuměl požadavku, ale odmítá ho splnit. Klient nemá k danému zdroji povolen přístup. 404 Not Found» Zdroj nebyl na poskytnuté URI nalezen. 409 Conflict» Požadavek nemohl být dokončen vzhledem ke konfliktu se současným stavem zdroje. 500 Internal Server Error» Server narazil na neočekávanou chybu své vnitřní služby. 2.2 Příklad komunikace Mějme tedy RESTové rozhraní fungující na protokolu HTTP. Pro množinu jeho URI identifikátorů si zavedeme pojem koncové body (endpoints). Rozhraní bude představovat knihovní systém. Zdroje budou reprezentovány jako application/xml. Jeho vstupním bodem nechť je URI Klient pošle požadavek GET na koncový bod /books. GET /books HTTP/1.1 Host: library.org Accept: application/xml... Klientovi se od serveru dostane odpovědi se status kódem 200. HTTP/ OK Content-Type: application/xml Content-Length:... 13

24 2. Komunikace skrze RESTové rozhraní Tělo odpovědi reprezentaci XML obsahuje seznam dostupných knih. <?xml version="1.0"?> <books> <id title="the Fellowship of the Ring">1721</id> <id title="the Two Towers">1722</id> <id title="the Return of the King">1723</id> <id title="the Hobbit">1724</id>... </books> Pro klienta má význam hlavně id položky. Požadavkem na koncový bod /books/1724 si může vyžádat konkrétní knihu. GET /books/1724 HTTP/1.1 Host: library.org Accept: application/xml... V těle odpovědi obdrží požadovaný zdroj. <?xml version="1.0"?> <book> <id>1724</id> <title>the Hobbit</title> <author>j. R. R. Tolkien</author> <location section="fantasy">3-a</location> <status>available</status> <link rel="borrow" href="/borrowings" method="post"/> <link rel="return" href="/borrowings/1724" method="delete"/> <link rel="edit" href="/books/1724" method="put"/> </book> Odpověď obsahuje několik odkazů, které umožňují další práci se zdrojem. Uživatel se tedy rozhodne si knihu vypůjčit a pošle POST požadavek na URI borrowings je nadefinovaná kolekce výpůjček a je základní URI. Pozdějším GET požadavkem získá následující zdroj: 14

25 2. Komunikace skrze RESTové rozhraní <?xml version="1.0"?> <book> <id>1724</id> <title>the Hobbit</title> <author>j. R. R. Tolkien</author> <location section="fantasy">3-a</location> <status>borrowed</status> <link rel="return" href="/borrowings/1724" method="delete"/> <link rel="edit" href="/books/1724" method="put"/> </book> Přijatý zdroj se od předchozího stavu změnil. Pole status nyní značí, že je kniha vypůjčená a zdroj už neobsahuje odkaz na vypůjčení. Na ukázce tedy vidíme demonstraci principu HATEOAS. K uskutečnění komunikace skrze rozhraní stačilo klientovi znát vstupní bod a základní množinu metod protokolu HTTP. Zbytek komunikace se odvíjel na základě přijatých hypermédií. 15

26 3 Nefunkční požadavky kladené na RESTová rozhraní Nefunkční požadavek softwarové architektury definuje omezení a vlastnosti požadované po systému jako celku. Je nezávislý na konkrétní implementaci. Nadefinujme si několik nefunkčních požadavků, které v praxi na webová rozhraní klademe. Tyto požadavky mohou být ovlivněny jak kvalitou návrhu, tak specifikami konkrétní implementace, jazyka a použitého frameworku. [3, sekce 2.1] 3.1 Výkon Výkon je zásadním parametrem u jakéhokoliv softwaru, ať už se jedná o desktopovou aplikaci, nebo webovou službu. Správné nastavení interakcí mezi komponentami v REST architektuře je dominantním faktorem pro uživatelem vnímaný výkon a efektivitu celého systému. Dříve jsme si určili, že naše rozhraní bude fungovat na protokolu HTTP, tedy s největší pravděpodobností na síti internet. Přenos dat na reálné síti je omezen několika parametry. Propustnost určuje velikost datového toku v jednom okamžiku. Započítáváme do něj samotný datový objem zprávy, i tzv. overhead přidaná data nutná k uskutečnění operace (např. HTTP hlavičky). Ta můžeme dělit na overhead potřebný k navázání spojení a overhead potřebný k uskutečnění každé interakce. Šířka pásma udává limit maximálního možného datového toku v dané síti, z jejíž celkové velikosti je naší aplikaci přístupná pouze část použitelná šířka pásma. Při návrhu je důležité si uvědomit, jaký průměrný datový objem budeme zpracovávat vůči granularitě jednotlivých komponent. Návrh, který podněcuje k malým, silně typovaným interakcím bude efektivní v aplikaci která pracuje primárně s malými a častými datovými přenosy. Časté interakce však působí velký overhead. U návrhu počítajícího s velkými datovými přenosy si tedy můžeme dovolit větší overhead a slaběji typované interakce, ale musíme klást větší důraz na koordinaci jednotlivých komponent a dobré řízení komunikace samotné. [3, sekce 5.1] 16

27 3.2 Škálovatelnost 3. Nefunkční požadavky kladené na RESTová rozhraní Dobře škálovatelná architektura je taková architektura, která umožňuje pozdější rozšiřování o větší množství komponent a nárůst interakcí mezi nimi. Může být zlepšena rozdělením funkcionality mezi více komponent, jejich zjednodušováním, či manuální správou komunikace na základě monitorování přenosu. O škálovatelnosti rozhraní architekt rozhoduje hlavně v iniciální fázi návrhu, a při výběru použitých technologií. REST architektura už svou definicí poskytuje dobrý základ pro budoucí škálovatelnost. 3.3 Jednoduchost Jednoduchosti docílíme správným aplikováním dříve nadefinovaných principů jako oddělení zodpovědností či uniformnost rozhraní. Uniformní rozhraní, které poskytuje protokol HTTP (daná množina metod, variabilita hypermédií) k tomuto značně přispívá. K mnohem snadnějšímu porozumění a implementaci přispějeme i správným rozdělením funkcionality mezi jednotlivé komponenty. Systém by se tedy měl skládat z většího množství méně komplexních komponent, které dělají pouze to co mají, a dělají to správně. 3.4 Modifikovatelnost I když je možné naimplementovat systém, který uspokojuje požadavky jeho uživatelů, nedokážeme zaručit že se tyto požadavky po čase nezmění. Dobře modifikovatelný systém by měl tyto změny umožňovat. V případě webových aplikací, jejichž části mohou přesahovat mezinárodní hranice, musí návrh počítat i s umožněním postupných, nebo částečných modifikací, a to i za běhu ostatních komponent systému (dynamická modifikovatelnost). [3, sekce 5.1] Pod modifikovatelnost můžeme zařadit i parametry jako rozšiřitelnost (možnost lehce přidat novou funkcionalitu), přizpůsobitelnost (možnost dočasně přizpůsobit komponentu ke specifické funkci), konfigurovatelnost (možnost upřesnit nastavení komponenty, např. na práci s jiným datovým typem) či znovupoužitelnost (zda jsou části systému bez nutnosti změny použitelné i v jiných aplikacích). 17

28 3. Nefunkční požadavky kladené na RESTová rozhraní 3.5 Přenositelnost Aplikace je přenositelná, pokud je schopna fungovat i v jiném prostředí, než na jakém byla vyvinuta. Prostředím rozumíme zejména jiné operační systémy, či jejich rozdílné verze. K dobré přenositelnosti přispívají implementace na virtuálních strojích (např. Java virtual machine, Android Runtime) či využití standardizovaných datových typů (XML, JSON). 3.6 Spolehlivost Na spolehlivost můžeme nahlížet jako na faktor, pod kterým je systém náchylný k selhání, za předpokladu že selže pouze některá z jeho částí. Lepší spolehlivosti docílíme přidáním redundantních komponent (může vést ke snížení výkonu), povolením monitorování, či eliminací tzv. single point of failure konkrétní komponenty, na které závisí větší část funkcionality. Při selhání takové komponenty obvykle dochází k nefunkčnosti větší části systému. 18

29 4 Návrh RESTových rozhraní 4.1 Stanovení funkčních požadavků K návrhu RESTového rozhraní můžeme přistupovat několika způsoby. Ať už se rozhodneme použít tužku a papír, či webovou službu využívající popisovací jazyk, na začátku návrhu je vždy vhodné provést systematickou analýzu požadavků (requirements engineering). Tedy nadefinovat si případy užití, a z nich vyplývající funkční požadavky. Použiji dřívější příklad jednoduchého rozhraní knihovního systému. Toto rozhraní, spravující jediný druh zdroje knihy, by mohlo být v praxi součástí většího systému, se správou výpůjček a kartiček návštěvníků knihovny. Návrh UI klienta, či komplexnějšího databázového modelu však není předmětem této kapitoly, ani této práce. Na demonstraci návrhových postupů REST architektury tedy toto jednoduché rozhraní postačí. Rozhraní musí být schopno: Vypsat seznam všech knih v knihovním katalogu. Vypsat seznam knih v určité sekci. Vypsat seznam vypůjčených/dostupných knih. Přidat novou knihu. Upravit stávající knihu. Smazat vyřazenou knihu. 4.2 Datové popisovací jazyky Po ujasnění funkčních požadavků je důležité si přesně nadefinovat zdroj. Rozhraní tedy bude pracovat nad zdrojem reprezentujícím knihu. Většina dnešních RESTových rozhraní využívá primárně JSON, či XML reprezentaci. Z průzkumu vykonaného americkou společností Layer 7 v roce 2014 vyšlo, že 50,5% API designérů dává přednost 19

30 4. Návrh RESTových rozhraní formátu JSON, 47,8% preferuje XML reprezentaci a pouhých 1,6% používá jiný formát. [2] Pro oba datové formáty existují schémata, jež popisují jejich strukturu XML Schema XSD (XML Schema Definition) vzniklo v roce 2001 jako doporučení konsorcia W3C. Specifikuje formální strukturu elementů XML souborů. XSD se primárně používá k podrobnému ověření validity všech elementů v dokumentu. Má několik výhod oproti dřívějším XML schématům, kterými jsou Document Type Definition (DTD), či Simple Object XML (SOX). Syntaxe XSD je v XML, jedná se tedy vždy o validní XML dokument, a k interpretaci není potřeba žádného přechodného parsování. Mezi jeho další výhody patří možnost generování specifického XML dokumentu ze schématu, generování lidsky čitelné dokumentace (vhodné zvlášť u komplexních XML souborů), či podpora XSLT transformací. XSLT umožňují transformovat XML dokument do jinak strukturovaného XML dokumentu, či do jiného formátu, ať už HTML, PDF, PNG či PostScript. [10] Co se týče samotné struktury dokumentu, pomocí XSD jsme schopni nadefinovat vlastnosti XML dokumentu jako: 20 Jména jednotlivých elementů, jejich pořadí, atributy a datové typy (xs:string, xs:decimal, xs:integer, xs:boolean, xs:date, xs:time). Implicitní a neměnné hodnoty elementů. Restrikce maximálních a minimálních hodnot typu xs:integer. Předdefinované komplexní typy elementů (<xs:complextype>) včetně jejich rozšiřování (<xs:extension base="personinfo">). Indikátory výběru podřízených prvků elementu (<xs:all>, <xs: choice>, <xs:sequence>), či jejich počtu (atributy minoccurs, maxoccurs). Vzory atributů (<xs:pattern value="male female">). Substituční skupiny umožňující definovat více názvů elementů (např. <item> a <predmet> se stejně definovaným obsahem). [11]

31 4. Návrh RESTových rozhraní Ukázka syntaxe XSD Schema je k nalezení v příloze 1.2 na straně JSON Schema JSON Schema specifikuje strukturu JSON dokumentu. Je silně založeno na konceptech XSD. Slouží také hlavně k validaci a generování JSON dokumentů. Vznikalo jako internetový draft specifikace vydaná komisí Internet Engineering Task Force (IETF). Jeho poslední verzí je verze 4, vydaná v roce [12] Oproti XSD je JSON Schema samopopisné a lépe lidsky čitelné. I JSON Schema nabízí široké možnosti definice struktury dokumentu podobné XSD, jako jsou definice názvů, pořadí a datových typů elementů, indikátory počtu, unikátnosti, či možnost rozšiřování komplexnějších JSON podobjektů. [13] Ukázka syntaxe JSON Schema je k nalezení v kapitole A.2 na straně CRUD Nad zdroji budeme provádět operace, které budou měnit jejich stav v perzistentním úložišti. Pro to existují 4 základní operace, které označujeme zkratkou CRUD Create, Read, Update, Delete (vytvoř, přečti, uprav, smaž). CRUD metody budou namapovány na HTTP metody, respektive POST, GET, PUT, a DELETE. [14] 4.4 Koncové body Stanovme si koncové body, na kterých budou zdroje skrze API dostupné. Vstupním bodem bude hostitelské jméno serveru fiktivní URI Kolekce všech knih bude dostupná pod koncovém bodem /books. Většinou se jedná o uspořádaný seznam obsahující URI jednotlivých knih. Konkrétní knihu pak bude možno získat pod koncovým bodem /books/{id}, kde id reprezentuje evidenční číslo knihy. Koncový bod je URI šablonou, jelikož obsahuje dosaditelný parametr. [1, str. 35] URI šablony dovolují specifikovat i libovolné množství dalších parametrů. Tyto parametry lze využít např. při přístupu ke kolekci 21

32 4. Návrh RESTových rozhraní Koncový bod GET PUT POST DELETE /books /books/{id} Vrátí seznam všech knih v katalogu Vrátí konkrétní knihu Nahradí celý seznam novým Nahradí knihu, pokud neexistuje, vloží novou Přidá novou knihu do katalogu Nepoužívá se, ekvivalentní GET na /books Smaže všechny knihy Smaže knihu Obrázek 4.1: Vztah mezi koncovými body a HTTP metodami o velkém množství záznamů. Zdroje v kolekci můžeme vracet po stránkách, či filtrovat na základě nějakého z parametrů zdroje. Jsme tak schopni předejít zbytečnému přetěžování služby, či vracení nepřehledného množství dat. [1, str. 38] Odpovídající atributy pro stránkování mají typicky následující syntaxi: Po dosazení parametrů: Či v případě filtrování: Těmto, a dalším implementačně závislým parametrům návrhu jako je např. verzování zdrojů se budu věnovat více v praktické části práce. 4.5 Popisovací jazyky rozhraní Pro návrh a strukturovaný popis různých typů rozhraní existují tzv. popisovací jazyky rozhraní (interface description languages). Jedná se typicky o druh formálního jazyka, který je strojově i lidsky čitelný, a kterým architekt dokáže rozhraní popsat nezávisle na jazyku, ve kterém bude implementováno. Pro návrh webových služeb už dříve vznikly popisovací jazyky, zejména WSDL2.0 (Web Services Description Language) a WADL 22

33 4. Návrh RESTových rozhraní (Web Application Description Language). Ani jeden z nich však není úplně vhodný k návrhu RESTových rozhraní jako takových. Brání jim v tom jejich špatná lidská čitelnost, jsou totiž typicky automaticky generované z kódu. WSDL ani nedisponuje dostatečnými prostředky k popisu REST API. [15] To dalo za vznik jazykům specificky určeným pro návrh RESTových rozhraní. Patří mezi ně např. OpenAPI (Swagger), RAML nebo API Blueprint OpenAPI Specification OpenAPI si od svého počátku prošlo zajímavým vývojem. Vzniklo v roce 2010 pod názvem Swagger jako prostředek pro vývoj internetového slovníku Wordnik. Od svého vzniku si Swagger získal mezi uživateli značnou popularitu. V roce 2015 společnost SmartBear, která Swagger udržovala, oznámila, že specifikaci daruje společnosti Open API Initiative, financované organizací Linux Foundation. [16] Swagger je dnes kompletní specifikací a frameworkem pro návrh, tvorbu a vizualizaci RESTových rozhraní. Také si klade za cíl udržet klientský kód a dokumentaci v synchronizaci s aktuální verzí rozhraní samotného. Dokumentace metod, parametrů a datových modelů dokáže být pevně provázaná s kódem na serveru a umožňuje rozhraní udržovat stále aktuálním. Specifikace Swagger nabízí několik nástrojů k návrhu a integraci své funkcionality: Swagger UI Knihovna HTML, Javascript, a CSS nástrojů, schopná generovat dokumentaci rozhraní na základě předpisu dodržujícího Swagger specifikaci. Swagger Editor Uživatelské rozhraní sloužící k návrhu RESTových API bez nutnosti instalace. K definici používá značkovací jazyk YAML. Uživatelské rozhraní editoru je znázorněno na obrázku 4.2 na následující straně. 23

34 4. Návrh RESTových rozhraní SDK Generators Soubor generátorů založených na šablonách schopných produkovat implementační kód ze Swagger specifikace. Umožňuje generovat kód v jazycích jako Java, Javascript, PHP, Ruby, Python a dalších. Obrázek 4.2: Ukázka YAML syntaxe v Swagger editoru RAML RESTful API Modeling Language (RAML) je dalším z popisovacích jazyků sloužících pro návrh RESTových rozhraní. Klade důraz na snadnou lidskou čitelnost, znovupoužitelnost a dodržování dobrých programátorských návyků. [17] RAML je od svého počátku open source a vzniklo pro něj mnoho nástrojů třetích stran. Část z nich cílí právě na možnost návrhu různých druhů rozhraní. Na rozdíl od Swaggeru je RAML schopen i návrhu hybridních rozhraní, tedy takových rozhraní, která nutně nesplňují všechny požadavky REST architektury. [18] Zápis 4.3 na následující straně je velmi podobný specifikaci Swagger. RAML specifikace též využívá značkovací jazyk YAML 1.2. Pro 24

35 4. Návrh RESTových rozhraní ukázku zápisu jsem použil Anypoint API Designer od společnosti MuleSoft, která je jedním z členů RAML workgroup, pracovní skupiny starající se o vývoj RAML. Obrázek 4.3: Syntaxe RAML specifikace v Anypoint API Designer API Blueprint API Blueprint je dalším z popisovacích jazyků webových rozhraní. Nese na podobné vlně jako RAML a Swagger. Není však tolik rozšířený a nemá tedy třeba vlastní editor. Jazyk však implementuje populární služba apiary.io. Apiary.io bylo jedním z prvních a po dlouhou dobu jediným nástrojem určeným na design webových rozhraní. [19] Apiary mimo jiné také podporuje Swagger specifikaci. 25

36 5 Analýza frameworků REST architektura je jako koncept značně obecná a neváže se nutně na žádný programovací jazyk, nebo konkrétní typ webové aplikace. Mezi nejpopulárnější jazyky implementující REST architekturu, a tudíž jazyky disponující největším počtem dostupných frameworků, patří PHP, Python a Ruby. Není se čemu divit, jelikož tato trojice reprezentuje nejpopulárnější jazyky na webu. V těsném závěsu popularity se hlásí enterprise sféra, se dvěma největšími zástupci jazyky Java a C# (respektive platformou.net od Microsoftu). Za zmínku určitě stojí i stále relativně aktivní komunita okolo jazyka Perl. Ke konci pomyslného žebříčku najdeme i Node.js, oblíbený Javascriptový runtime. Pokud bychom však porovnávali popularitu Javascriptových API na klientské straně, nacházel by se bezpochyby na prvním místě. [20] V Java Enterprise Edition je od verze 6 dostupná JAX-RS Java API for RESTful Web Services. Jedná se o oficiální specifikaci pro tvorbu RESTových rozhraní. Vznikala za asistence Roye Fieldinga, autora REST architektury. Mnoho frameworků třetí strany jej implementuje (RESTEasy, Restlet, Jersey), některé zase jdou vlastní cestou (Spring, Dropwizard). Ve zbytku kapitoly provedu analýzu těchto nejpoužívanějších open source REST API frameworků. 5.1 Spring framework Spring framework je open source aplikační framework pro jazyk Java. Jeho první verze vyšla v roce 2003 a v současnosti jeho vývoj vede společnost Pivotal Software. Jeho hlavním cílem bylo zjednodušení vývoje enterprise aplikací, kde našel své hlavní využití. Umožňuje vývoj lightweight aplikací nad Java Enterprise Edition platformou. Jeho využití ale není limitováno pouze na velké aplikační systémy. S příchodem komponent jako je Spring Boot umožnil integraci své funkcionality i do jednoduchých Javovských aplikací. [21] Spring je od začátku vývoje silně modulární a nabízí množství komponent a funkcionalit pro různé typy aplikací. Jeho architektura (viz obrázek 5.1 na následující straně) je rozdělena do několika modulů (Core jádro frameworku, Web tvorba webových aplikací, Data 26

37 5. Analýza frameworků Access/Integration správa a převod dat). K implementaci RESTových rozhraní se využívá zejména komponenta Spring MVC z modulu Web. Obrázek 5.1: Architektura Spring frameworku [22, sekce 2.2] Výhody Jedná se o enterprise framework Dobrá integrace s ostatními frameworky a knihovnami Zdaleka nejlepší modularita komponent Jednoduchý a přímý přístup k datům v relačních databázích (Spring Data JPA) Bezpečnost: OAuth, Single Sign On, CAS, Social Sign On, Open ID Široká komunita, kvalitní dokumentace s příklady Nevýhody Nesplňuje JAX-RS standard (Spring kód není přenositelný na JAX-RS) Java EE CDI má oproti Springu dokonalejší dependency injection Obrázek 5.2: Posouzení vlastností frameworku Spring 27

38 5. Analýza frameworků 5.2 RESTEasy RESTEasy framework je jedním z projektů portfolia JBoss.org, vyvíjeného společností RedHat. Jedná se o plně certifikovanou a přenosnou implementaci specifikace JAX-RS 2.0. A jedná se zároveň o projekt, který vznikl pod JCP (Java Community Process), což je proces, který umožňuje různým firmám podílet se na vývoji nových součástí Java platformy. [23] RESTEasy běží na jakémkoliv servlet kontejneru 1, ale nejlepší integraci se logicky těší JBoss Application Server. Výhody Přenositelnost mezi množstvím aplikačních serverů (běžících na JDK 6) Mockup server pro JUnit testování GZIP komprese komunikace na straně klienta i serveru (vede k lepšímu výkonu) Podpora autorizačního standardu OAuth2, digitálních podpisů a šifrování Dobrý model interceptorů 2 Nevýhody Nadržuje ostatním produktům od JBoss Obtížné generování WADL Obrázek 5.3: Posouzení vlastností frameworku Restlet 5.3 Jersey Jersey framework je open source framework postavený na JAX-RS specifikaci, kterou obohacuje o funkcionalitu a množství utilit k ulehčení vývoje RESTových služeb. Oproti zbytku frameworků je relativně nový (2012). [25] Mezi ostatními implementacemi JAX-RS se jedná o zdaleka nejmodulárnější. [26] Jedná se o referenční implementaci od společnosti Oracle. Na vývoji frameworku se téměř výhradně podílí čeští vývojáři z Pražské pobočky Oracle. [27] Je dostupný v balíku s GlassFish serverem. 1. Servlet kontejner je komponenta webového serveru obsahující servlety. Servlet umožňuje rozšířit schopnosti webového serveru přidáním různorodého dynamického obsahu běžícího na Java platformě. [24] 2. Třída umožňující implementaci dodatečné aplikační logiky, kterou lze provést při přerušení HTTP požadavku. 28

39 5. Analýza frameworků Výhody Vysoký výkon a využití aktuálních návrhářských postupů Dobrý URI routing a URI building Integrace s dalšími frameworky jako Grizzly, Netty či Spring Nevýhody Chaotická implementace dependency injection od verze 2.0 Verze 1.x využívají starou implementaci JAX-RS Mnoho online zdrojů je pro verze 1.x, a jsou tím pádem nevhodné pro 2.x Nevyžaduje servlet kontejner Chybí bezpečnostní protokol OAuth 2.0 Hladká integrace JUnit testů 5.4 Restlet Obrázek 5.4: Posouzení vlastností frameworku Jersey Restlet je nejstarším z RESTových frameworků pro Javu jeho první verze vyšla v roce Umožňoval implementaci REST architektury ještě předtím, než se stala tak populární. [28] Implementace JAX-RS se stala součástí Restletu až později. A i navzdory jeho věku a současné konkurenci je stále jedním z nejoblíbenějších. [25] Oproti většině dnešních frameworků jeho syntaxe není založená na anotacích. Má unifikované klient-server API, zatímco JAX-RS specifikace je navržena pro zpracování na straně serveru. [29] Je dostupný pro velké množství platforem (Java SE/EE, Google AppEngine, OSGi, GWT, Android) a schopný operovat i přes širší množství komunikačních protokolů. Výhody Jedná se o enterprise framework Množství podporovaných platforem Dobrá modularita Nevyžaduje servlet kontejner Podpora mnoha komunikačních protokolů Dobré routování URI a filtrace zdrojů Velké množství doplňků Množství dedikované literatury Nevýhody Komplexní a těžký na naučení Uzavřená komunita Malá popularita (na úkor Jersey) Obrázek 5.5: Posouzení vlastností frameworku Restlet 29

40 5. Analýza frameworků 5.5 Dropwizard Dropwizard se nachází někde na pomezí mezi knihovnou a frameworkem. Organizuje nejlepší dostupné Javovské komponenty na tvorbu webových služeb do jednoho frameworku. Stejně jako Spring, i Dropwizard je značně modulární a výsledné aplikace jsou poměrně malé, což snižuje čas potřebný k vývoji či údržbě. Na rozdíl od Springu se ale nehodí k implementaci enterprise aplikací. Nevyžaduje externí aplikační server, jelikož využívá zabudovaný Jetty server. Na implementaci REST služeb používá částí Jersey frameworku. [25] Výhody Rychlý proces implementace a nasazení projektu Podpora monitorování výkonu a běhu (knihovna Metrics) Vysoký výkon Dobrá modularita Server vždy spouští main() metoda, což usnadňuje debugging Široká komunita podporující vývoj Nevýhody Modularita ztěžuje dokumentaci (u komponent třetích stran) Starší verze používají zastaralé komponenty třetích stran Horší zpracování chybových zpráv Obrázek 5.6: Posouzení vlastností frameworku Dropwizard 5.6 Shrnutí Spring framework je rozsáhlý a může se zdát, že pro vytvoření jednoduchého REST API je použití Springu přehnaně zbytečné. To není lež, jelikož RESTové micro frameworky (jako je RESTEasy či Dropwizard), které splní svou práci rychle a jednoduše. Projekt Spring Boot však umožňuje uživatelům na webu nakonfigurovat jaké části Springu ve své aplikaci potřebují, na základě čehož vygeneruje spustitelný projekt připravený k vlastní implementaci. Spring Boot také nabízí přímo předkonfigurované projekty třeba právě pro tvorbu REST API. [30] Pokud je prostředí aplikace stavěno na produktech od JBoss (např. JBoss Application server), je RESTEasy jasnou volbou. Spolu s Jersey se také jedná o jeden z nejstabilnějších dostupných frameworků. [31] 30

41 5. Analýza frameworků Jersey je ale spíše pouze referenční implementací JAX-RS API. REST- Easy je více otevřené novým nápadům. [28]. Dropwizard se snaží k problematice přistupovat z jiné strany a spíš zabaluje to nejlepší co můžou ostatní nabídnout do jedné, ale flexibilní skládačky. Toto je jeho slabinou a zároveň silnou stránkou. Velká závislost na komponentách třetích stran může působit nečekané problémy. Kvalita a přehlednost dokumentace těchto komponent taky často značně kolísá, což práci neulehčuje. [25] Pokud aplikace nestojí a nepadá na RESTových rozhraních, jakákoliv z JAX-RS implementací (RESTEasy, Restlet, Jersey) splní svůj účel dostatečně. Záleží pak na vývojáři, které vlastnosti a možnosti integrace konkrétního frameworku mu vyhovují víc. Mezi JAX-RS implementacemi tedy není nijak markantní rozdíl v syntaxi či obtížnosti učení. Výběr jakéhokoliv z diskutovaných frameworků tedy není vyloženě špatnou volbou. 31

42 6 Implementace RESTového rozhraní V praktické části se budu zabývat implementací reálného rozhraní fungujícího jako součást backendu aplikace CleverAnalytics. Clever- Analytics je cloudová platforma pro lokační analýzu. Umožňuje vizualizovat data nad mapou a pomocí množství nadefinovaných metrik měřit různé parametry trhu, typicky u pobočkové sítě. Mezi tyto parametry patří např. obchodní potenciál, podíl na trhu, věrnost zákazníků, konkurence či vnitřní kanibalizace prodejen. CleverAnalytics k tomuto účelu kombinuje data poskytnutá zákazníkem s open daty, demografickými a kartografickými daty poskytovanými státem. Typickým uživatelem aplikace je ředitel pobočkové sítě retailového prodejce či banky, případně marketingový ředitel, který na základě poskytnuté analýzy rozhoduje o umístění nových poboček, uzavření starých, či jejich relokaci. Platforma jako taková je ale poměrně flexibilní, umožňuje i vizualizace roznosu letáků, dojezdových dob, obslužnosti restaurací, či sítě plynovodů. [32] Obrázek 6.1: UI CleverAnalytics, analýza vnitřní konkurence [32] 32

43 6. Implementace RESTového rozhraní Jako poskytovatele datového úložiště a serverového prostředí CleverAnalytics využívá Amazon Web Services (AWS). AWS nabízí množství služeb pro cloudové systémy. CleverAnalytics z nich využívá např. EC2 instance pro běh mikroslužeb, RDS Relational Database Service pro databáze, úložiště S3 pro přenosy a zálohy dat, či Route 53 jako DNS službu. V testování je i např. Amazon RedShift sloupcová databáze umožňující až několikanásobně rychlejší zpracování dotazů než databáze klasické (zvlášť v případě OLAP 1 a business intelligence úloh). Backend aplikace je napsán v Javě, frontend v Javascriptu. Architektura backendu funguje na principu mikroslužeb (microservices) malých, nezávislých procesů, které spolu komunikují na základě nadefinovaných rozhraní a formují tak jednu velkou aplikaci. Platforma je multitenantní, na serveru tedy běží instance aplikace, která slouží různým skupinám uživatelů. Členové těchto skupin mají specifická přístupová práva do určitých části aplikace v případě CleverAnalytics jde o zákaznické projekty. Každý projekt běžící na platformě má svou databázi s daty a metadaty. Formát, kvalita a struktura klientských dat se často liší, a je zapotřebí práce datových analytiků k uvedení dat do stavu zpracovatelného platformou. Metadata naopak určují jednotlivé komponenty UI klienta, metriky, pohledy a tzv. datasety. Ty popisují mapování mezi logickou a fyzickou vrstvou dat uložených v databázi, jejich vzájemné propojení a způsob interpretace. 6.1 Funkční požadavky Jednou z mikroslužeb fungujících na backendu platformy je právě metadata služba. Její součástí je REST API na zmiňované datasety, klíčový typ metadata objektů. Datasety jsou nadefinovány jako JSON objekty, jejich přesná struktura je popsána v kapitole na straně 35. Dosud byly uloženy jako pole JSON objektů v jednom *.json souboru na disku produkčního serveru. API v původní verzi fungovalo pouze jako správce souborů, tj. data v plaintextu přijímalo, ukládalo na server a na požádání vystavovalo frontendovému klientovi. 1. OLAP technologie uložení dat v databázi umožňující uspořádání velkých objemů dat tak, aby byla data přístupná a srozumitelná uživatelům zabývajícím se analýzou obchodních trendů a výsledků (business intelligence). [33] 33

44 6. Implementace RESTového rozhraní Mým úkolem bylo navrhnout robustnější řešení pro rozhraní této mikroslužby. Rozhraní mělo mít následující funkční požadavky: Provádět CRUD operace nad objekty typu dataset (jak kolekcí tak jednotlivými prvky). Objekt dataset specifikovat pomocí JSON Schema, a z něj generovat DTO objekty pro REST API. Rozvrstvit aplikaci na vrstvu controlleru, servisní a perzistentní. DTO objekty převádět na POJO a pomocí ORM frameworku perzistovat do relační databáze. Podporovat stránkování a verzování zdrojů. 6.2 Výběr technologií Protože je architektura systému postavena na mikroslužbách, bylo logické zvolit jako základní stavební kámen Spring Boot. Spring Boot současně nabízí nejlepší podporu psaní mikroslužeb v Javě. [34] Aplikace jsou velmi snadno konfigurovatelné a mají možnost sdílení konfigurace mezi ostatními službami. Spring Boot také dovoluje sestavení aplikace do spustitelného JAR souboru včetně embedovaného Tomcat serveru, a tak umožňuje spuštění více mikroslužeb jako samostatných procesů v rámci jednoho operačního systému na různých portech bez nutnosti velkého aplikačního serveru. Aplikace bude součástí enterprise systému, použití Springu je tedy opodstatněné. Webová část zodpovědná za funkcionalitu REST API se bude skládat z několika komponent Springu konkrétně Spring MVC, Spring HATEOAS a Spring Data JPA. Dataset si v Javě nadefinujeme jako objekt typu POJO 2. Serializaci a deserializaci JSON objektů přijatých a odeslaných controllerem bude obstarávat Jackson JSON processor. Jackson je víceúčelová Java knihovna sloužící právě ke zpracování JSON formátu. Inspirovala se JAXB, standardní Java knihovnou pro parsování XML. [35] POJO objekty datasetů budou automaticky 2. Plain Old Java Object. Jednoduchá třída obsahující proměnné, konstruktor, gettery a settery. Takováto třída se jednoduše serializuje do objektů typu JSON či XML. 34

45 6. Implementace RESTového rozhraní generovány z JSON Schema pomocí pluginu jsonschema2pojo. [36] Jsonschema2pojo dokáže generované POJO objekty anotovat přímo Jackson anotacemi a JSR 303 anotacemi. Objektový datový model reprezentovaný POJO objekty se ale bude lišit od relačního datového modelu tříd, které budou ukládány do databáze. Převod mezi těmito druhy objektů má na starosti mapper. Jedním z nejpoužívanějších mapperů pro Javu je Dozer, ten ale vyžaduje velký overhead. Rozhodl jsem se tedy pro rychlejší Orika mapper. [37] Mapování Java tříd na tabulky databáze bude zajišťovat ORM framework, já jsem zvolil Hibernate ORM od JBoss. Hibernate umožňuje snadné mapování POJO do databáze s použitím Spring Data JPA. Má podporu transakcí i verzování zdrojů. Jako databázi jsem se rozhodl zvolit PostgreSQL. Je to ověřená relační databáze s progresivní komunitou a dynamickým vývojem. Umožňuje kombinovat tradiční relační model s dynamickým přístupem k ukládání dat využití datového typu JSONB pro ukládání a práci s JSON formátem v databázi. Datasety jsou poměrně malé a je potřeba kontrolovat integritu několika jejich parametrů pomocí cizích klíčů. Tento typ kontrol by musel být u NoSQL databází součástí aplikačního kódu. PostgreSQL tak díky pokročilé podpoře práce s JSON daty stírá značnou část výhod, pro které by stálo za to zvažovat použítí NoSQL databáze, jako například MongoDB. Celá aplikace bude sestavena pomocí nástroje Apache Maven. Java Maven project je definován několika XML soubory, které popisují strukturu jeho modulů, interní a externí závislosti, či pluginy. 6.3 Vrstva controlleru Vrstva controlleru zajišťuje REST API komunikaci, překlad výjimek na HTTP kódy a validaci příchozích požadavků jak z pohledu správnosti vstupů, tak uživatelských oprávnění Objektový datový model Základním zdrojem, se kterým bude rozhraní pracovat je dataset. Datasety jsou metadata, tedy data popisující strukturu dat v databázi. Je důležité nezaměňovat metadata za data. Existují v zásadě 2 druhy 35

46 6. Implementace RESTového rozhraní datasetů dataset typu WFS 3 a typu DWH 4. Dataset typu WFS reprezentuje dataset, který popisuje mapování tabulek ve WFS službě. Dataset typu DWH naopak popisuje mapování v DWH službě. DWH dataset popisuje i jednotlivé sloupečky a klíče v databázi. Podrobný popis struktury je znázorněn v ER diagramu A.1 na straně 60. Obrázek 6.2: Znázornění hierarchické struktury datasetů Ukázka reálného datasetu typu DWH v příloze A.4 na straně 59. Základní dataset je tedy nadefinován následujícím schématem: { "$schema": " "id": " "type": "object", "javatype": "com.cleveranalytics.service.metadata.rest.dto.dataset.datasetdto", "properties": { "properties":{ "id": "properties", "javatype": "java.util.map<string, Object>", "type": "object" }, 3. Web Feature Service služba umožňující sdílení geografických informací ve formě vektorových dat 4. Data Warehouse typ relační databáze umožňující řešit úlohy zaměřené převážně na analytické dotazování nad rozsáhlými soubory dat 36

47 6. Implementace RESTového rozhraní "searchby": { "id": "searchby", "type": "array", "items": { "type": "string", "minlength": 1 } }, "ref": { "javatype": "com.cleveranalytics.service.metadata.rest.dto.dataset.datasettype", "oneof": [ { "$ref": "metadata.dataset.dwhtype.schema.json" }, { "$ref": "metadata.dataset.wfstype.schema.json" } ] } }, "additionalproperties" :false, "extends": { "javatype": "com.cleveranalytics.service.metadata.rest.dto.dataset.metadataobject" }, "required": [ "ref" ] } Vidíme, že v klíčích javatype se nachází odkazy na konkrétní Java třídy, které ve vygenerovaném POJO objektu budou referencovány. Jsonschema2pojo se podívá do daného balíčku (com.cleveranalytics. service) a při generování konkrétní třídu jako datový typ dosadí. V klíči ref je nadefinováno Java rozhraní DatasetType, které implementují třídy DatasetWfsType a DatasetDwhType. JSON Schema toto řeší klíčovým slovem oneof. V podobjektu extends ještě vidíme odkaz na třídu MetadataObject. Tato POJO třída je předkem každého metadata objektu, tedy i datasetu. Obsahuje základní klíče, které mají všechny metadata objekty společné (id, name, description a podobně). Dataset tuto třídu rozšiřuje, tudíž ke klíčům nadefinovaným v MetadataObject přidává sobě specifické properties, searchby, a hlavně ref. Tato třída není generovaná ze schématu, jelikož obsahuje i klíče pro interní zpracování (version), které nechceme v JSON 37

48 6. Implementace RESTového rozhraní reprezentaci vystavovat, a současná verze JSON Schema neumožňuje nastavit specifický klíč jako skrytý. Vygenerovaný POJO objekt datasetu třída DatasetDTO 5 tedy vypadá takto: package @JsonPropertyOrder({ "properties", "searchby", "ref" }) public class DatasetDTO extends private Map<String, private List<java.lang.String> searchby = private DatasetType ref; } // other attributes, getters and setters Model-View-Controller Komponenta Spring MVC slouží k implementaci webových služeb, neslouží tedy výhradně k implementaci RESTových rozhraní. Podpora implementace těchto rozhraní přicházela inkrementálně a dostatečné úrovně se dočkala až ve verzi Spring 3. MVC (model-view-controller) 5. DTO Data Transfer Object, objekt datového modelu používaný k převodu na JSON či XML reprezentaci. 38

49 6. Implementace RESTového rozhraní je architektonický vzor, definující rozdělení funkcionality webové aplikace do tří částí. Model (model) definuje datový model, spravuje data, vystavuje je na požadavky controlleru View (pohled) zobrazuje datový výstup, ať už se jedná o tabulku, či webovou stránku Controller (řadič) reaguje na události (typicky pocházející od uživatele) a zajišťuje změny v modelu nebo pohledu Obrázek 6.3: Diagram vzoru MVC Ve Springu třídu controlleru označujeme Tato třída obsahuje metody které pomocí parametru RequestMethod namapujeme na HTTP metody. indikuje, že třída DatasetDTO musí být obsažena v těle požadavku. zase značí, že URI GET požadavku musí obsahovat id požadovaného datasetu. Servisní vrstvu reprezentuje třída DatasetService, podrobněji se jí věnuje kapitola 6.4 na straně 43. Třída je označena jelikož jde o třídu vloženou závislostí (dependency injection). [38] 39

50 6. Implementace = "/rest/projects/{projectid}/metadata/datasets") public class DatasetController private DatasetService can_update_metadata = RequestMethod.POST) public final DatasetDTO datasetdto) { DatasetDTO saveddatasetdto = datasetservice.create(datasetdto); return ResponseEntity.ok().body(savedDatasetDTO); = "/{id}", method = {RequestMethod.GET}) public ResponseEntity<DatasetDTO> final String id) { DatasetDTO datasetdto = datasetservice.getbyid(id); ETag etag = new ETag(datasetDTO.getVersion()); return ResponseEntity.ok().eTag(etag.getStringValue()).body(datasetDTO); } } // other methods Návratový typ obou metod je ResponseEntity s třídou DatasetDTO jako tělem HTTP odpovědi. HTTP status kódem je v případě úspěšného získání zdroje 200 OK. V případě neúspěchu je vyhozena příslušná výjimka, která je třídou DatasetExceptionHandler přeložena na HTTP zprávu s odpovídajícím chybovým statusem a zprávou Stránkování zdrojů V případě GET požadavku na kolekci /metadata/datasets může nastat případ, že controller vrátí kolekci o větším množství datasetů. Spring HATEOAS umožňuje implementaci stránkování zdrojů pomocí PagedResources. 40

51 6. Implementace RESTového rozhraní Listing 6.1: Výňatek z metody getalldatasets() Page<DatasetDTO> datasets = datasetservice.getall(pageable); PagedResources<DatasetResource> pagedresources = pagedassembler.toresource(datasets, resourceassembler, new Link(), "self")); Pošleme požadavek na odpovídající koncový bod. URI je doplněna parametry, které můžou specifikovat velikost stránky, její číslo, nebo klíč pro řazení prvků (&sort=id). GET /rest/projects/abc123/metadata/datasets?page=0&size=10 HTTP/1.1 Host: secure.cleveranalytics.com Accept: application/json Odpověď v podobě stránky poté obsahuje odkazy na zbývající stránky, obsah tedy pole JSON objektů, a detaily o aktuální stránce. { "links": [ { "rel": "self", "href": "/rest/projects/abc123/metadata/datasets?page=0&size=10" }, { "rel": "next", "href": "/rest/projects/abc123/metadata/datasets?page=1&size=10" } ], "content": [... ], "page": { "size": 10, "totalelements": 37, "totalpages": 4, "number": 0 } } Verzování zdrojů Je vhodné ke každému zdroji přiřadit proměnnou, která bude značit jeho verzi. Verze může být reprezentována datem, kontrolním součtem (MD5 hash), či jednoduše celým číslem. Na úrovni HTTP komunikace je reprezentována HTTP hlavičkou ETag (viz tabulka 2.2 na straně 11), 41

52 6. Implementace RESTového rozhraní na úrovni objektového modelu jako proměnná version v třídě Dataset a v databázi jako sloupeček version. O inkrementaci verze se stará Hibernate, dokáže automaticky inkrementovat proměnnou označenou v databázi, při jakékoliv její změně. [39] To umožňuje implementaci tzv. optimistického zamykání. Optimistické zamykání slouží k zabránění možné ztráty provedených změn, pokud se zdrojem pracuje více klientů současně. Mějme uživatele A a B, kteří chtějí zároveň pracovat s jedním datasetem. Obrázek 6.4: Sekvenční diagram optimistického zamykání Oba uživatelé si vyžádají konkrétní dataset, s iniciální verzí 0. Oba na něm provedou změny, ale uživatel A pošle požadavek PUT jako první a verze se inkrementuje. Když se teď uživatel B pokusí odeslat své úpravy, server mu odpoví statusem 412 Precondition Failed. Uživatel B si proto musí GET požadavkem vyžádat novou verzi, kterou pak úspěšně odešle, viz obrázek 6.4. Druhou variantou je zamykání pesimistické, které zdroj uzamkne hned jakmile je kýmkoliv vyžádán a dokud uživatel neodešle nové změny, nikdo jiný s ním nemůže pracovat. 42

53 6.4 Servisní vrstva 6. Implementace RESTového rozhraní Servisní vrstva zajišťuje aplikační logiku včetně řízení transakcí při komunikaci s perzistentní vrstvou. Tato vrstva také zajišťuje překlad z DTO objektů používaných na REST API na entitní objekty, které budou navržené s ohledem na využití vlastností relační databáze Mapování mezi datovými modely DTO třídy deserializované z JSON objektů přijatých controllerem jsou opatřené anotacemi Jackson mapperu, a zajišťují určitou logickou část aplikace. Při implementaci jsem se pokoušel přímo tyto objekty namapovat pomocí Hibernate do databáze, to se však ukázalo jako značně nerozumné. Ukázalo se totiž, že pro uložení do databáze musí daná třída splňovat jiná specifika, a také proto, že v kódu třídy opatřené takovým množstvím anotací se jednoduše nedalo vyznat. Vytvořil jsem si tedy paralelní datový model schopný splnění podmínek kladených databází a ORM frameworkem. Mezi tyto podmínky patří rozdílné datové typy jedné proměnné (HashMap na objektovém modelu JSONObject na relačním), nutnost využití abstraktních tříd oproti rozhraním, či nutnost vytvoření id pro každou z podtříd datasetu (DatasetWfsType, DwhProperty atd.) v relačním modelu, zatímco v objektovém byly bezvýznamné. DTO objekty a entitní objekty však bylo potřeba mezi sebou převádět mapovat. Mapování mezi různými druhy objektů se v Javě dá řešit manuálně, to ale ústí ve velké množství opakujícího se kódu zaplněného velkým množstvím setterů. Vybral jsem si tedy mapper Orika (viz kapitola 6.2 na straně 34). Implementace mapperu se nachází v třídě DatasetMapper. Orika využívá návrhových vzorů Facade a Factory k samotnému mapování. Dvě třídy (DatasetDTO.class a Dataset.class) se zaregistrují v DefaultMapperFactory, jejich proměnné jejichž název nebo datový typ se liší se pak explicitně uvedou, a provede se mapování pomocí BoundMapperFacade. V ukázce 6.2 na následující straně využívám speciální convertery nadefinované na převod proměnných, jejichž datový typ se v modelech liší. 43

54 6. Implementace RESTového rozhraní Listing 6.2: Ukázka metody mapující DTO objekt na entitní public Dataset mapdtotoentity(datasetdto datasetdto) { mapperfactory.classmap(datasetdto.class, Dataset.class).fieldMap("properties", "properties"). converter("jsonpropertiesconverter").add().fieldmap("additionalproperties","additionalproperties").converter("jsonpropertiesconverter").add().exclude("accessinfo").exclude("ref").bydefault().register(); BoundMapperFacade<DatasetDTO, Dataset> boundmapper = mapperfactory.getmapperfacade(datasetdto.class, Dataset.class); } return boundmapper.map(datasetdto); JPA repozitář JPA repozitář provádí operace nad entitami v databázi. V Javě pro tento účel existuje Java Persistence API (JPA). Práce s JPA bývá ale často zdlouhavá a plná opakujícího se kódu. V případě implementace CRUD repozitářů operujících nad různými entitami, je nutno implementovat funkcionalitu pro každý z nich zvlášť. Spring Data JPA repozitář přidává úroveň abstrakce nad Java Persistence API. Rozšiřuje CrudRepository poskytující CRUD operace a PagingAndSortingRepository zajišťující stránkování a řazení. [40] Umožňuje nadefinovat rozhraní Javovské třídy a implementaci operací poskytne JPA samo. Implementaci předpisu metody repozitář dokáže poznat i na základě hlavičky metody. Metoda findbyname() v ukázce 6.3 z hlavičky ví, že má provádět operaci READ nad objektem Dataset na základě proměnné name. Typické metody, jako findbyid se nemusí ani definovat jako předpis metody v rozhraní, repozitář je umí implicitně (findone). Repozitáře ale umožňují i specifickou práci s databází, k čemuž slouží tzv. query metody. Těm lze pomocí nadefinovat přesný SQL dotaz, který mají provádět. Parametr nativequery značí, že se jedná o SQL dialekt nativní pro PostgreSQL. 44

55 6. Implementace RESTového rozhraní Listing 6.3: Ukázka Spring Data JPA public interface DatasetRepository extends JpaRepository<Dataset, String> { Dataset findbyname(string = "SELECT d FROM Dataset d") Page<Dataset> = "DELETE FROM dataset WHERE metadata_id LIKE :id", nativequery = true) void deletedatasetwhereid(@param("id") String id); } // other methods 6.5 Perzistentní vrstva Entitní vrstva zajišťuje práci s daty v relační databázi. Ty jsou pak pomocí Hibernate ORM frameworku namapovány na databázi PostgreSQL. Entitní vrstva také ukazuje možnost využití PostgreSQL JSON typu ve spojistosti s JPA Relační datový model Relační datový model definuje strukturu vhodnou k uložení datasetů do databáze. Jelikož datasety samotné mají hierarchickou strukturu (obrázek 6.2 na straně 36), je nutné k uložení jednoho datasetu několik tabulek. Datasety typu DWH můžou navíc obsahovat neomezené množství DWH parametrů a cizích klíčů. Datový model také obsahuje dvě místa kde nastává členění: V případě ref proměnné entity Dataset, která může mít dva druhy DatasetWfsType a DatasetDwhType. U properties entity DatasetDwhType, která může být buď typu DwhProperty nebo DwhForeignKey. 45

56 6. Implementace RESTového rozhraní ER diagram celého relačního datového modelu je dostupný v příloze A.1 na straně PostgreSQL typ json Některé konkrétní klíče datasetů nemají na serveru žádný význam a není u nich potřeba kontrola syntaxe či datové integrity (např. properties a additionalproperties). Jednou z vlastností PostgreSQL, která se pro tento případ hodí, je jeho podpora ukládání JSON dat. V PostgreSQL existují datové typy json a jsonb. Akceptují identický vstup, rozdílem je způsob jejich uložení. Typ json uchová přesnou kopii vstupu v JSON formátu, zatímco jsonb jej uloží v dekomponovaném binárním formátu, což zlepšuje rychlost zpracování. V tomto případě ale nebudeme ukládat nijak velké části JSON dat, takže json postačí. Nutností je z hlediska Javy nadefinování vlastního PostgreSQL dialektu třída JsonPostgreSQLDialect a přidání vlastního uživatelského typu třída JsonUserType. Pro relační reprezentaci JSON dat používám třídu JSONObject, která je ve skutečnosti datovým typem Map<String, JsonValue>, který dokáže Hibernate do databáze namapovat jednoduše ORM ORM objektově relační mapování (object-relational mapping) je technika, která umožňuje automatickou konverzi dat mezi relační databází a objekty objektově orientovaného jazyka. ORM umožní objektovou třídu namapovat na tabulky a sloupečky v databázi. To dovoluje vývojáři se do určité míry odstínit od nutnosti práce s SQL dotazy nad konkrétní relační databází. Já jsem k implementaci zvolil framework Hibernate ORM. Hibernate je stejně jako Spring Data JPA implementací Java Persistence API. Umožňuje perzistenci tříd využívajících OOP 6 principů, jako jsou dědičnost, polymorfismus, kompozice, či kolekce. Na ukázce 6.4 na následující straně vidíme základní použití frameworku. Třída reprezentuje entitu v databázi, ji specifikuje přímo na tabulku s vlastním jménem. Anota- 6. Object Oriented Programming objektově orientované programování 46

57 6. Implementace RESTového rozhraní cemi nad třídou definujeme také vlastní datové typy (zde JsonUserType zmiňovaný v na předchozí straně). Proměnná properties je namapována jako s Proměnná searchby ukazuje možnost jednoduchého mapování kolekcí s využitím Referenční typ ref odkazuje na abstraktní třídu DatasetRefType, která tvoří pomyslného prostředníka mezi třídami DatasetWfsType a DatasetDwhType, kterých může ref nabývat. Oba dva možné podtypy datasetů tuto abstraktní třídu rozšiřují a tak obsahují id primární klíč původního datasetu. Každý dataset může být buď jednoho, nebo druhého typu a tak mezi nimi platí kardinalita 1:1, symbolizována Listing 6.4: Ukázka použití Hibernate na = "JsonObject", typeclass = JsonUserType.class )}) public class Dataset extends MetadataEntityObject = = "JsonObject") private private List<DwhProperty> searchby = new = "dataset", cascade = CascadeType.ALL, fetch = FetchType.EAGER) private DatasetRefType ref; } // other variables and methods 47

58 6. Implementace RESTového rozhraní 6.6 Testy Unit testy Funkcionalita aplikace je rozdělená do vrstev, klasickým typem unit testů zde tedy myslíme mapovací testy mezi objektovým a relačním datovým modelem konkrétně třídy WfsDatasetMappingTest a DwhDatasetMappingTest. Testy si načtou čerstvý dataset ze složky src/test/resources/json. Ten namapují na relační model, zase zpět na objektový, a poté provedou kontrolu konzistence parametrů vráceného DTO datasetu. Využívají servisní vrstvu reprezentovanou třídou DatasetService. Tato třída je do testů vložena která vytvoří mock verzi třídy vhodnou pro testy. Toto je jednou z vlastností testovacího frameworku Mockito Integrační testy Integrační testy běží nad spuštěnou službou a kontrolují konzistenci její funkcionality. Protože musí být spouštěny právě nad běžící službou, je jejich běh při kompilaci projektu vypnut. Stejně jako unit testy, načtou si soubory z adresáře src/test/resources/json na disku. Těchto testů existují dva druhy DatasetIntegrationTest a ApplicationContextIntegrationTest. První test simuluje reálné použití rozhraní na úrovni controlleru. Druhý zmiňovaný kontroluje pouze správné nastavení Spring kontextu, centrálního rozhraní udržujícího konfiguraci Springové aplikace. Podívejme se tedy na datasetové integrační testy. V metodě označené která se vykonává před každým testem, si nainicializují klienta založeného na RestTemplate, viz příloha A.3 na straně 61. Třída RestTemplate nabízí metody jako postforobject(), getforobject() nebo exchange(), představující ekvivalentní HTTP metody. Požadavek se sestaví pomocí třídy RequestEntity a odešle. Vrácená odpověď v těle ResponseEntity je pak kontrolována na úrovni jednotlivých parametrů. A to buď pomocí metody assertequals() z frameworku JUnit, či jako komplexní JSON objekt pomocí metody assertequals() z testovacího miniframeworku JSONAssert. Tato me- 48

59 6. Implementace RESTového rozhraní toda dokáže kontrolovat ekvivalence JSON objektů se zanedbáním pořadí klíčů, či klíčů nadbytečných, v praxi se pořadí klíčů negarantuje Zátěžové testy Rozhraní jako takové není stavěné na velké datové objemy, přesto není na škodu si zátěžové testy vytvořit. Rozhraní používá hlavně frontendový klient, či datoví analytici sestavující projekty editací metadat. V obou případech komunikace skrze rozhraní probíhá spíš na úrovni jednotlivých datasetů, které nejsou typicky větší než v řádu desítek kb. Zátěžové testy jsem vytvořil v aplikaci JMeter a jsou k nalezení v příloze, konkrétně v adresáři JMeter. Doporučuji spouštět testy ve verzi JMeteru 2.13 a vyšší, narazil jsem totiž u starších verzí na problémy s předáváním HTTP hlaviček. Projektový soubor datasets.jmx si tedy otevřeme v JMeteru. Obsahuje dvě skupiny vláken Metadata new a Metadata post/get. První reprodukuje podobný případ použití jako integrační testy, tedy vytvoření datasetu, jeho získání, upravení, uložení nového a smazání. Druhý typ pouze vytváří a získává datasety. U těchto testů není na závadu, že občas selžou, jelikož zde testujeme chování aplikace při zátěži, ne přímo správnost jeho funkcionality. Tyto vlákna lze vypínat a zapínat kliknutím pravého tlačítka a volbami Enable/Disable. Nedoporučuji míchat spouštění obou skupin. Testy samotné pak spustíme tlačítkem Start. Po doběhnutí testů a získání výsledků doporučuji pro přehlednost příštího běhu vymazat reporty tlačítkem Clear. Výsledky testů je možné sledovat v komponentě Summary report. Výsledky jednotlivých HTTP volání pak v komponentě View Results Tree. Komponenta Graph results dokáže zjistit parametry jako průměrná doba odpovědi, šířka pásma a podobně a vizualizovat je v grafu. Na základě těchto výsledků pak nastavujeme parametry jako je velikost paměti virtuálního stroje na produkci, či limit šířky pásma v konfiguraci Apache Tomcat serveru. 49

60 6. Implementace RESTového rozhraní 6.7 Shrnutí praktické části Implementace této aplikace byla milníkem v mém programátorském životě, a zkušenosti získané v jejím průběhu jsou k nezaplacení. Jednalo se o moje první větší setkání se Spring frameworkem a REST architekturou ze strany vývojáře, ne uživatele. S vědomostmi, které mi tento projekt dal, bylo podle mě tedy víc než vhodné přetavit jej v část této bakalářské práce. Služba v současné době funguje jako jedna z mikroslužeb na backendu CleverAnalytics. Produkční verze rozhraní se ale liší, primárně ve dvou bodech: Aplikace nevyužívá jednu databázi, ale databázový connection pool, jelikož každý projekt má databázi vlastní. Multitenance aplikace toto vynucuje. Uchovávat data v jedné databázi je navíc bezpečnostní riziko. Druhým velkým rozdílem je autentikace a autorizace. Na všech REST API CleverAnalytics je vyžadována autorizace skrze OAuth 2.0. Pro jednoduchost a možnost použití aplikace bez nutnosti mít CleverAnalytics účet s dostatečnými přístupovými právy, je právě tento (velmi důležitý) aspekt vynechán. V úvodní kapitole 6 na straně 32 zmiňuji, že kromě datasetů existuje více druhů metadata objektů. Toto je právě možnost budoucího rozšíření aplikace. Do budoucna se plánuje implementace nové verze rozhraní i pro UI komponenty, či pohledy. Ty však nemají takový význam pro backend aplikace, a tak zatím zůstávají jako soubory na disku produkčního serveru. Některé z využitých technologií (např. jsonschema2pojo) jsou relativně nové, a ve stavu, kdy vycházející verze nabízejí mnoho nové a očekávané funkcionality. Aktualizace aplikace s postupem těchto technologií je též na místě. Na škálovatelnost se kladl důraz, věřím tedy že jakýkoliv další vývoj bude hladký. 50

61 7 Závěr Cílem této bakalářské práce bylo seznámit čtenáře s principy, které definují REST architekturu webových rozhraní, a uvést ho do širšího kontextu jejich návrhu. Čtenář následně získal přehled o dostupných REST frameworcích v jazyce Java. Znalosti získané z těchto dvou prvních částí práce by pak měl schopný aplikovat při implementaci skutečného RESTového rozhraní. REST architektura je dnes velmi populární. To připisuji hlavně její jednoduchosti, efektivitě a výborné škálovatelnosti. Není omezena ani platformou, ani jazykem. Popularita architektury také zapříčinila větší otevřenost webových aplikací. Společnosti jako Facebook, Twitter či Amazon staví svá rozhraní na REST architektuře. To dává více prostoru vývojářům, kteří chtějí vyvíjet aplikace čerpající data od těchto velkých jmen. Stejně dobře může RESTové rozhraní sloužit jako interní komunikační kanál, třeba právě mezi několika mikroslužbami a tvořit tak jeden silný, decentralizovaný systém, jak jsme mohli vidět v praktické části. Tato práce pro mě byla velkým přínosem. K REST architektuře jsem se dostal spíše jako praktik a velmi si cením přehledu, který jsem získal při jejím psaní. Právě zasazení tohoto tématu do širšího kontextu je něco, co bych v praxi nezískával snadno. Jsem si vědom toho, že ač REST architektura patří k hitům webového vývoje posledních let, stále existují typy další, jako jsou XML-RPC nebo SOAP. A má znalost nich je značně povrchní. Do budoucna by tedy určitě stálo za to si okruhy rozšířit a možná postoupit o úroveň výš a zanalyzovat různé druhy webových rozhraní jako takových. 51

62 Literatura [1] Jim Webber, Savas Parastatidis a Ian Robinson. REST in Practice. First Gravenstein Highway North, Sebastopol, California: O Reilly Media, říj [2] Saul Caganoff. Layer 7 Survey Strong Growth Predicted for Hypermedia APIs. cit url: news/2014/03/ca-api-survey. [3] Roy Thomas Fielding. Architectural Styles and the Design of Network-based Software Architectures. PhD Dissertation. University of California, Irvine, [4] R. Fielding a J. Reschke. Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. RFC RFC Editor, červ url: [5] Roy Fielding. REST APIs must be hypertext-driven. cit Říj url: [6] et al. R. Fielding. Hypertext Transfer Protocol HTTP/1.1. RFC RFC Editor, červ url: html/rfc2616. [7] Hypertext Transfer Protocol. cit url: wikipedia.org/wiki/hypertext_transfer_protocol. [8] D. Kristol. HTTP State Management Mechanism. RFC RFC Editor, říj url: [9] Todd Fredrich. HTTP Status Codes. cit url: http: // [10] Margaret Rouse. XSD (XML Schema Definition). cit url: [11] W3C. XML Schema Tutorial. cit url: w3schools.com/xml/schema_intro.asp. [12] Francis Galiegue. JSON Schema: core definitions and terminology. Internet-draft. Internet Engineering Task Force, led url: [13] Michael Droettboom. Understanding JSON Schema, Release 1.0. cit url: understanding-json-schema/understandingjsonschema.pdf. 52

63 LITERATURA [14] Martin Heller. REST and CRUD: the Impedance Mismatch. cit url: application-development/rest-and-crud--the-impedancemismatch.html. [15] Laura Heritage. API description languages. cit url: n-languages. [16] Open API Initiative. OpenAPI specification wiki. cit url: [17] Christian Vogel. RAML Version 1.0: RESTful API Modeling Language. cit url: https : / / github. com / raml - org / raml - spec / blob / raml - 10 / versions / raml - 10 / raml - 10.md. [18] Saul Caganoff. Designing an Event Log API with RAML. cit url: [19] Kin Lane. There Are Four API Design Editors To Choose From Now. cit url: 21/there-are-four-api-design-editors-to-choose-fromnow/. [20] Adam DuVander. What Programming Language is Most Popular with APIs? cit url: eweb.com/news/what-programming-language-most-popularapis/2013/06/03. [21] Roman Pichlík. Spring Framework představení J2EE lightweight kontejneru. cit říj url: erval. cz / clanky / spring - framework - predstaveni - j2ee - lightweight-kontejneru. [22] Rod Johnson et al. Overview of Spring Framework. cit url: spring-framework-reference/html/overview.html. [23] Bill Burke et al. RESTEasy. cit url: resteasy.jboss.org/. [24] What is Servlet Container? cit url: programcreek.com/2013/04/what-is-servlet-container/. [25] Dragan Gaić. Top 8 Java RESTful Micro Frameworks. cit červ url: 53

64 LITERATURA [26] Adam Gent. How to choose between Jersey, Apache Wink and JBoss RESTEasy? cit srp url: low.com/a/ [27] Pavel Buček et al. Jersey The Team. cit url: [28] Solomon Duskis. JAX-RS Vendor Comparisons Part I. cit zář url: entry/jax_rs_vendor_comparisons_part. [29] Jerome Louvel. JAX-RS Frameworks. cit zář url: [30] Phillip Webb et al. Spring Boot Reference Guide. cit url: nt/reference/htmlsingle/#getting-started-introducingspring-boot. [31] What s the best RESTful web framework to use with Java? cit url: com/ Whats- the- best- RESTful-web-framework-to-use-with-Java. [32] Ondřej Tomas et al. CleverAnalytics: cloudová platforma pro lokační analýzu. cit url: cz/. [33] Online Analytical Processing. cit url: cs.wikipedia.org/wiki/online_analytical_processing. [34] Oleg Shelajev. Why Spring is Winning the Microservices Game. cit ún url: rebellabs / why - spring - is - winning - the - microservices - game/. [35] Tatu Saloranta. Jackson Project Home. cit url: [36] Joe Littlejohn. jsonschema2pojo. cit url: https: //github.com/joelittlejohn/jsonschema2pojo. [37] Anatoliy Sokolenko. Dozer vs Orika vs Manual. cit květ url: http : / / blog. sokolenko. me / 2013 / 05 / dozer-vs-orika-vs-manual.html. [38] Building a RESTful Web Service. cit url: https : / / spring.io/guides/gs/rest-service/. 54

65 LITERATURA [39] Dmitry Shpika. RESTful HTTP: concurrency control with optimistic locking. cit srp url: ub.io/ /restful-http-concurrency-optimisticlocking.html. [40] Ken Chan. What is difference between CrudRepository and JpaRepository interfaces in Spring Data JPA. cit pros url: [41] Leonard Richardson, Mike Amundsen a Sam Ruby. RESTful Web APIs. First Gravenstein Highway North, Sebastopol, California: O Reilly Media, zář [42] apiary.io. API Blueprint. cit url: y.io/how-it-works. [43] Rossen Stoyanchev. A Comparison of Spring MVC and JAX-RS. cit ún url: springmvc_jsx-rs. [44] Bill Burke et al. RESTEasy JAX-RS documentation. cit url: Final/userguide/html_single/index.html. 55

66 A Appendix A.1 Ukázky kódu Listing A.1: Ukázka syntaxe XSD <?xml version="1.0" encoding="utf-8"?> <xs:schema xmlns:xs=" <xs:element name="book"> <xs:complextype> <xs:sequence> <xs:element name="id" type="xs:int"/> <xs:element name="title" type="xs:string"/> <xs:element name="author" type="xs:string"/> <xs:element name="location" type="xs:string"> <xs:complextype> <xs:attribute name="section" type="xs:string"/> </xs:complextype> </xs:element> <xs:element name="status" type="xs:string"> <xs:element name="link" maxoccurs="unbounded"> <xs:complextype> <xs:attribute name="rel" type="xs:string"/> <xs:attribute name="href" type="xs:string"/> </xs:complextype> </xs:element> </xs:sequence> </xs:complextype> </xs:element> </xs:schema> 56

67 A. Appendix { } Listing A.2: Ukázka syntaxe JSON Schema "$schema": " "type": "object", "properties": { "book": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "author": { "type": "string" }, "location": { "type": "object", "properties": { "section": { "type": "string" }, "bookshelf": { "type": "string" } }, "required": [ "section", "bookshelf" ] }, "status": { "type": "string" }, "links": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "title", "author", "location", "status", "links" ] } }, "required": [ "book" ] 57

68 A. Appendix { } Listing A.3: Ukázka datasetu typu DWH "id": "jw65ou2p98vxb1", "type": "dataset", "name": "mystores", "searchby": [ "id", "name", "street" ], "ref": { "type": "dwh", "table": "stores", "primarykey": "id", "properties": [ { "type": "integer", "name": "id", "column": "id" }, { "type": "string", "name": "name", "column": "name" }, { "type": "string", "name": "street", "column": "street" } ] } 58

69 A. Appendix { } Listing A.4: Ukázka datasetu typu WFS "id": "qd3jf91an47pof6", "name": "atms", "type": "dataset", "title": "Bankomaty", "properties": { "period": "7/2015", "includingvat": true }, "ref": { "type": "wfs", "workspace": "$projectid", "layer": "bankomaty_routing_5_min", "primarykey": "can_id" } 59

70 A. Appendix A.2 Obrázky Obrázek A.1: ER diagram databáze datasets 60