REST contract-first: Swagger & Gradle

U webových služeb mám rád přístup contract-first. Jsem 100% přesvědčen, že tak vzniká lepší design i lepší API.

V případě SOAP webových služeb je to celkem běžné. (Teda pokud webové služby "nedesignují" programátoři - to pak většinou skončí "vyzvracením" interního kódu na veřejnost.)

Ohledně REST-ových služeb mi to přijde jako minoritní způsob. To je jednak škoda a jednak problém. Ono to nakonec vždycky nějak funguje. Ale jen výjimečně pak vznikají API, které vývojáři milují.

Jak tedy na REST contract-first službu? Následuje popis, který jsem použil na stávajícím projektu a se kterým jsem - po vychytání (Swagger) much - spokojen.

Jak by to mělo fungovat?

Mám dost jasnou představu, jak by celistvý přístup contract-first měl fungovat. Pokud máte jiný postup, nebo se mnou nesouhlasíte, budu rád, když se podělíte v komentářích. Můj zobecněný přístup vypadá takto:

1. Napsat kontrakt v nějaké rozumně standardizované a obecně přijímané specifikaci.
2. Vygenerovat potřebný kód, zejména model a rozhraní (API).
3. Vygenerovaný kód by měl být v adresáři, kde build tool očekává zdrojové kódy.
4. Generování a kompilace vygenerovaného kódu je součástí standardního build lifecycle (není potřeba je spouštět samostatně).
5. Ideálně, generování a kompilace probíhá jen tehdy, pokud došlo ke změně specifikace.
6. Implementaci rozhraní si píšu sám, ručně.

Swagger

Swagger je soubor nástrojů, které se točí kolem OpenAPI specifikace. Za OpenAPI si můžete představit "něco jako WSDL pro REST". Pro naše potřeby nás budou zajímat dva nástroje: Swagger Editor pro napsání specifikace a Swagger Codegen pro generování kódu ze specifikace.

Swagger Editor

Swagger Editor je webový editor, který si můžete vyzkoušet on-line, ale pro reálnou práci bude lepší ho mít lokálně. Je trochu otravné, že kvůli tomu musíte nainstalovat Node.js, ale jinak má lokální verze víc šikovných funkcionalit.

Swagger Editor

Mimochodem, za celým Swaggerem stojí společnost SmartBear, která dělá SoapUI, takže očekávejte něco podobného - je to proklatě použitelné a v detailech mrzce nedotažené. A mizerná dokumentace.

Swagger specifikace

Swagger specifikace může mít dva formáty: JSON, nebo YAML. Jak na zmíněném projektu, tak v článku jsem zvolil YAML - jednak je to čitelnější pro lidi a pak, aspoň na projektu, to nebudou číst jenom programátoři.

Takže, contract-first. Začneme jednoduchou Swagger specifikací, která nám odpoví na otázku Života, Vesmíru a vůbec:

Swagger Codegen

Swagger Codegen je Java knihovna s CLI rozhraním. Swagger se chlubí, že pro generování kódu podporuje 20 serverových a 40 klientských řešení. Moje ukázka je ve Springu, ale klidně si vyberte svoji oblíbenou platformu.

Swagger Codegen CLI

Jak už jsem to naťuknul výše, ne všechno je ve Swaggeru perfektní - kolegové si dost stěžovali na kvalitu a použitelnost generovaných artefaktů pro JAX-RS a pro C#.

Já jsem sice s výsledkem spokojený a dělá to přesně, co jsem chtěl, ale bylo potřeba to poladit - strávil jsem cca 2 dny experimentováním, než jsem se dostal do stavu "akceptováno". Dva dny se mohou zdát hodně, ale jednak to byla zábava a jednak se to v blízké budoucnosti bohatě vrátí.

No, komand-lajna je sice boží, ale my se s ní patlat nebudeme, jsme přece profíci - použijeme Gradle.

Gradle

Pokud na Gradle Plugin Portálu zadáte heslo Swagger, vyjede vám 7 pluginů. Trochu jsem se bál, abych si nemusel napsat vlastní Gradle plugin, jako se mi to stalo u JAX-WS, protože žádný plugin nedělal, co jsem očekával. Ale nakonec po pročtení GitHubu a vyzkoušení jsem vybral plugin org.hidetake.swagger.generator, který šel rozumně ohnout pro moje potřeby.

Konfigurace zmíněného pluginu v build skriptu build.gradle může vypadat následovně (po ořezání ostatních věcí, které nás z hlediska Swaggeru nezajímají).


Podstatné věci na uvedeném skriptu:

• V závislostech nám přibyla konfigurace swaggerCodegen.
• Kvůli Swagger anotacím generovaným do API tříd je potřeba přidat závislost na swagger-annotations. To je sice otravný, ale asi nutná daň za použití Swaggeru. Naštěstí má ta knihovna jen 20 kB.
• Cílová platforma, pro kterou generujeme, je definovaná atributem language.
• Aby se nám negeneroval veškerý Swagger čurbes, omezíme generované artefakty atributem components, kdy říkáme, že chceme jenom model a api.
• Adresář s vygenerovanými artefakty je potřeba přidat ke zdrojovým souborům pomocí sourceSets. (To už není plugin, ale čistý Gradle.)
• A poslední řádek předsadí v lifecyclu task generateSwaggerCode před kompilaci Java kódu.

Bohužel, tím jsme s konfigurací ještě neskončili - tady to plugin mohl dotáhnout ještě dál. Sofistikovanější nastavení je potřeba dotáhnout v souboru config.json:


Tady stojí za zmínku dvě věci:

• Jednak prázdný atribut sourceFolder, to aby nám Swagger nevygeneroval duplicitně zanořené adresáře.
• A potom říkáme, že chceme vygenerovat jenom rozhraní (atribut interfaceOnly), aby nám Swagger rovnou negeneroval prázdné dummy kontrolery. (Možná použitelné jako stuby, pokud generujeme jenom jednorázově.)

A je to. Pokud spustíme build příkazem gradle build, dostaneme následující strukturu, kdy Swagger specifikace je v adresáři src/main/swagger a generovaný kód v adresáři src/generated/swagger:

Adresářová struktura projektu se Swagger definicí a generovaným kódem

Ukázkový projekt

Pro potřebu článku jsem vytvořil malý projekt na Bitbucketu, který vygeneruje potřebný kód a jde spustit v embeddovaném Jetty. Stačí naklonovan a spustit gradle jettyRun.

• sw-samuraj/blog-rest-contract-first

Měli byste ho vyzkoušet - minimálně vám odpoví na nejzákladnější otázku života. A vesmíru. A vůbec...

Související externí články

• Generování modelu z XSD (calavera.info)

Životní cyklus webových služeb

Jedním z aspektů SOA governance, který by se měl zvážit, pokud začneme s verzováním služeb, je definování a správa životního cyklu služeb (service lifecycle). Podobně jako se u vystavených rozhraní služeb snažíme, aby jejich změny byly pro uživatele předvídatelné a srozumitelné (k čemuž nám pomůže snaha o zpětnou kompatibilitu a verzování), měli bychom se podobně snažit o srozumitelnost a předvídatelnost ohledně (časové) dostupnosti služby samotné.

SOA jako taková, je poměrně volné téma, takže každý dodavatel řešení k ní přistupuje po svém (a většinou si ji ohýbá, podle svého technologického a business portofolia. Výjimkou je v tomto většinou open source, který se snaží implementovat podle návrhových vzorů a nemá přitom vedlejší úmysly). Podobně kreativní jsou výrobci i v oblasti životního cyklu SOA služeb. Pokud bysme chtěli vědět, jak vypadá nějaký "obecný" lifecycle, tak brzy zjistíme, že žádný takový není.

Service Lifecycle podle ITIL

Obecně má lifecycle nějaké hlavní fáze, rozdělené do dílčích fází. Např. Oracle má hlavní fáze pouze dvě (design a runtime), ITIL má tři (design, transition a operation) a IBM čtyři (model, assemble, deploy a manage).

Service Lifecycle podle IBM (zdroj IBM)

Pokud bychom si však přesto chtěli takový obecný lifecycle načrtnout, mohlo by to vypadat nějak takto: Na počátku je vždycky požadavek na novou business funkčnost, což by mělo vést k analýze - jestli může požadavek pokrýt nějaká stávající služba/y (nebo jejich kompozice), jestli bude potřeba stávající službu upravit (pak se musí udělat dopadová analýza - impact analysis), nebo jestli vznikne úplně nová služba. Když jsou tyto věci jasný, může se služba zaplánovat (např. kdy se nasadí na produkci).

Service Lifecycle podle Oracle (zdroj Oracle)

Následuje klasický vývojový cyklus, tj. analýza, vývoj a testování služby, nasazení na různá prostředí a pak se služba dostane do produkční fáze - začnou ji používat klienti. Časem se může stát, že služba už nebude splňovat požadavky na ni kladené, změní se požadavky a služba už nebude potřeba, anebo vznikne nová verze služby. Je čas, aby služba odešla do důchodu.

Skutečná podoba lifecyclu se ale bude vždycky odvíjet od procesu, který daná organizace má (nebo by měla mít) pro správu a řízení IT artefaktů. Protože SOA governance je pořád jen podmnožina (a rozšíření) IT governance.

Pokud máme vydefinovaný životní cyklus služby, naskýtá se otázka, kde jej spravovat. Ano, nabízejí se jednoduchá a přímočará řešení - už jsem viděl případy, kdy byla governance služeb držená v Excelu, nebo ji tvořily tři(!) tabulky v databázi. Pokud se však nechceme vydat touto svůdnou cestou a nechceme znovu vymýšlet kolo, je vhodné použít nějakou SOA governance repository.

Toto bývá dost často kamenem úrazu celé SOA governance, protože komerční repository jsou častokrát dražší, než celé zbývající SOA řešení. Pokud však nemáme velké oči (ještě nikdy jsem neviděl SOA governance implementovanou v celé své šíři), dají se, se stejným úspěchem, využít i open source řešení.

Například my jsme na projektu použili WSO2 Governace Registry, profesionální open source řešení, které (prozatím) splňuje naše požadavky. Ke každé registrované (a spravované službě) se dá přiřadit nějaký lifecycle (každá služba může mít jiný) a nastavit konkrétní fázi.

Lifecycle, který jsem pro aktuální projekt adaptoval vypadá následovně. Životní cyklus se skládá z několika stavů, kdy každý z nich může mít několik požadavků, které musí být splněny, aby se služba mohla posunout do dalšího stavu. Cyklus je znázorněn pomocí UML state diagramu, jednotlivé požadavky jsou zobrazeny jako responsibilities:

• Initial: Začátek lifecyclu, resp. procesu pro správu a životní cyklus služby. U nás takový proces de facto chybí a je nahrazen požadavky jednotlivých projektů. To je samozřejmě z hlediska SOA governance špatně - služba totiž nepřestane existovat jen proto, že je nasazena na produkci a je akceptována (což je pohled projektu).
• Development: Tady pro nás začíná design fáze lifecyclu (na obrázku zeleně).
• Contract created: bylo vytvořeno WSDL a bylo akceptováno konzumenty.
• Implemented: služba byla plně vyvinuta a nasazena na prostředí, kde ji můžou (integračně) otestovat klienti.
• Documented: služba byla zdokumentována. Pro nás to znamená, že byl jednak plně okomentáván kontrakt (elementy v XSD a služba a operace ve WSDL) a jednak byla zdokumentována orchestrace a externí komunikace služby pomocí CASE nástroje.
• In Test: Služba byla nasazena na testovací prostředí. Není explicitně řečeno jaké (FAT/SIT/UAT), protože jednotlivé požadavky se týkají různých prostředí.
• Smoke test passed: release manager ověřil, že služba po nasazení na SIT prostředí "žije".
• Test cases passed: test manager nechal projít všechny test casy a schválil posunutí služby do UAT testů.
• Accepted: služba byla akceptována v rámci UAT testů.
• Available: služba byla na sazena na produkční prostředí a je tak k dispozici konzumentům. Zde začíná run-time fáze cyklu (oranžově).
• Deprecation notification: konzumenti služby byli notifikování, že služba k nějakému datu přejde do stavu deprecated.
• Deprecated: služba je označena jako deprecated (určena k penzionování), nicméně stále je ještě k dispozici konzumentům. Pokud je služba označena jako deprecated, je zpravidla již k dispozici její novější verze (jejíž nasazení by mělo být synchronizováno s tímto stavem). Výjimkou může být, pokud je služba rušena bez náhrady - v tom případě je služba označena jako deprecated, ale není nasazena její novější verze.
• Retirement notification: konzumenti služby byli notifikováni, že služba k nějakému datu přejde do stavu retired.
• Retired: služba byla penzionovaná - stažena z používání a je klientům nedostupná. Služba v tomto stavu by stále měla být evidovaná v SOA governance repository. Například proto, aby bylo dohledatelné, v jakém časovém rozmezí byla služba aktivní apod.

Na závěr ještě malá ukázka, jak vypadá část lifecyclu v nástroji WSO2 Governace Registry:

U služby je vždy zobrazen aktuální stav cyklu, požadavky stavu jsou prezentovány checkboxy. Pokud služba splňuje podmínky přechodu do dalšího stavu (a tento stav skutečně již nastal), lze službu posunout do dalšího stavu tlačítkem Promote. Přechody mezi stavy a splnění požadavků lze svázat s formální kontrolou (např. kontrola verzí závislých artefaktů) a konkrétní uživatelskou rolí.

Související články:

• Verzování webových služeb, SOAP
• Verzování XSD v SOAP webových službách
• SOA governance, lehký úvod
• Enterprise integrace, messaging

Verzování XSD v SOAP webových službách

Když jsem psal minule o verzování SOAP webových služeb, zaměřil jsem se pouze na verzování v rámci WSDL. Letmo jsem také popsal WSDL strukturu, s tím, že jsem nijak neřešil definici datových typů. Tady se může skrývat další úskalí (nebo příležitost pro) verzování.

Datové typy jsou uvedeny v elementu types. Pokud není definice typů triviální, nebo pokud není ve službě definovaná pouze jedna operace, tak se zpravidla drží definice externě v XSD souboru a do WSDL se pouze naincludují (pokud chceme mít typy ve stejném namespace, jako má WSDL), nebo naimportují (pokud chceme, aby XSD mělo samostatný namespace).

Myslím, že je lepší používat element import. Kromě toho, že je to podmínka, aby kontrakt splňoval WS-I Basic Profile, tak to umožňuje dodržovat následující konvenci:

1. Součástí namespace WSDL je název služby.
2. Každá operace má svoje vlastní XSD (v němž je definovaný request a response).
3. Součástí namespace XSD je název služby a název operace.
4. Plus samozřejmě verzujeme.

Takže pokud bysme měli službu s názvem MyService a operaci s názvem myOperation, tak by namespacy vypadaly takto:

WSDL:
http://sw-samuraj.cz/ws/MyService-v1

XSD:
http://sw-samuraj.cz/ws/MyService-v1/myOperation

Podobně jako u WSDL, je v namespace uvedena pouze major verze a jelikož je už ji obsahuje název služby (MyService-v1), není potřeba ji duplikovat ještě v názvu operace.

Kromě namespaců verzujeme také samotný XSD soubor, např. myOperation-v1.2.xsd. Což nás staví před následující dilema. Představme si, že máme službu, která obsahuje dvě operace. Něco jako:

<?xml version="1.0" encoding="UTF-8"?>
<definitions
  targetNamespace=
      "http://sw-samuraj.cz/ws/MyService-v1"
  xmlns="http://schemas.xmlsoap.org/wsdl/"
  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">

  <types>
    <xsd:schema>
      <xsd:import
        namespace=
          "<trimmed>/MyService-v1/myOperation"
        schemaLocation="xsd/myOperation-v1.2.xsd"/>
      <xsd:import
        namespace=
          "<trimmed>/MyService-v1/yourOperation"
        schemaLocation="xsd/yourOperation-v1.2.xsd"/>
    </schema>
  </types>

  <!-- messages omitted -->

  <portType name="MyServicePort-v1.2">
    <operation name="myOperation">
      <!-- input, output and fault omitted -->
    </operation>
    <operation name="yourOperation">
      <!-- input, output and fault omitted -->
    </operation>
  </portType>

  <!-- binding omitted -->

  <!-- service omitted -->

</definitions>

Dilema zní: pokud dojde ke změně kontraktu pouze v rámci jedné operace, změním verzi pouze u XSD, které této operaci odpovídá, nebo změním verzi u všech XSD, které jsou součástí kontraktu? (V obou případech samozřejmě verzujeme WSDL tak, jak bylo uvedeno v předešlém článku.)

Pokud by se nám změnila operace myOperation, tak v prvním případě by import vypadal takto:

<types>
  <xsd:schema>
    <xsd:import
      namespace=
        "<shortened>/MyService-v1/myOperation"
      schemaLocation="xsd/myOperation-v1.3.xsd"/>
    <xsd:import
      namespace=
        "<shortened>/MyService-v1/anotherOperation"
      schemaLocation="xsd/anotherOperation-v1.2.xsd"/>
  </schema>
</types>

<portType name="MyServicePort-v1.3">
<!-- rest omitted -->

Výhodou této volby je, že verzujeme pouze XSD, u nichž opravdu došlo ke změně, zbytek necháváme na pokoji. Nevýhodou je, že verze XSD se nám rozjedou - jednak vůči sobě a jednak vůči WSDL. Reálně pak verzujeme XSD jako samostatný artefakt a ne jako součást kontraktu. To může být korektní situace, někdy vznikají XSD bez vazby na WSDL - v rozsáhlých projektech jsou často XSD vytvářena týmy analytiků a jejich import do WSDL zajišťují vývojáři.

V případě druhé možnosti by import vypadal následovně:

<types>
  <xsd:schema>
    <xsd:import
      namespace=
        "<shortened>/MyService-v1/myOperation"
      schemaLocation="xsd/myOperation-v1.3.xsd"/>
    <xsd:import
      namespace=
        "<shortened>/MyService-v1/anotherOperation"
      schemaLocation="xsd/anotherOperation-v1.3.xsd"/>
  </schema>
</types>

<portType name="MyServicePort-v1.3">
<!-- rest omitted -->

Nevýhodou této možnosti je, že musíme převerzovat všechy XSD v kontraktu, i ty, které se nezměnily (což se může zdát nepřirozené). Výhodou je, že kontrakt má jednotné verzování, takže mmj. nemusím kontrolovat jestli mám všechny XSD ve správné verzi. Zároveň je explicitně řečeno, že XSD je součástí kontraktu (ve smyslu objektové kompozice) a kontrakt (WSDL + XSD) by měl být vytvářen jedním týmem.

U nás na projektu o tom byla poměrně bouřlivá diskuze, kterou variantu zvolit. Argumenty byly poměrně vyrovnané a více méně odpovídaly těm uvedeným výše. Nakonec jsme se rozhodli pro jednotný kontrakt, takže se změnou verze WSDL převerzováváme i všechny XSD.

Verzování webových služeb, SOAP

Před časem jsem napsal lehký úvod do SOA governance. Chtěl bych se k tomuto tématu vracet a prezentovat principy, které postupně zavádíme na projektu. Momentálně nás daleko víc pálí věci, které spadají do design fáze služeb, takže řešíme věci jako verzování, reusabilita, granularita služeb apod.

Aspekt, který jsme řešili jako první (a nyní už i zavedli v praxi) je verzování služeb. Jelikož používáme řešení založené na SOAP webových službách (jak jinak v enterprise :-) podíval bych se právě na toto téma. Jestliže budu dále mluvit o webových službách (WS), mám tím vždy na mysli WS založený na SOAP.

Proč?

Otázka je, proč vlastně webové služby verzovat? Dejme tomu, že z nějakého důvodu chceme, na určitém prostředí, držet více verzí jedné služby. Tím důvodem může být např. to, že už máme nějaké stávající konzumenty dané služby a zároveň chceme touto službou poskytnout nové (business) funkcionality. Stávající klienti ovšem nemohou (nebo také odmítnou) přejít na novou verzi služby. Starou verzi služby tedy necháme funkční a zároveň nasadíme verzi novou. V případě SOA by toto mělo být definováno/podpořeno nějakou politikou, např. podpora více verzí služeb.

Kontrakt

Jak z hlediska SOA, tak z hlediska klienta se webová služba (a její konzumace) točí kolem kontraktu. Kontrakt, jako takový, se skládá z několika částí. Jednak definuje nějaké designové věci jako datové typy, zprávy a rozhraní (ve smyslu OOP). Dále definuje technologické záležitosti, tj. jaké se používají protokoly, jaké jsou endpointy služby. A konečně jsou to nefunkční požadavky.

Pro SOAPovské služby je tímto kontraktem WSDL (Web Service Definition Language). Pokud pomineme nefunkční požadavky (které stejně nejsou definovány ve WSDL namespacu, ale jinde), má WSDL následující strukturu (zeleně jsou designové části, červeně implementační):

• types - element definující pomocí XML Schema datové typy používané ve zprávách.
• message - abstraktní definice přenášených dat (zpráv), sestavená z typů definovaných v předešlém elementu. Každá zpráva se skládá z jedné a více logických částí (parts). Pokud je částí ve zprávě více, jde o službu založenou na RPC.
• portType - množina abstraktních operací, víceméně odpovídá rozhraní v OOP. Každá operace (metoda) by měla odkazovat vstupní a výstupní zprávu. Operace může být jedním ze čtyř typů: Request-response (klasika), One-way (obsahuje pouze vstupní zprávu), Notification (obsahuje pouze výstupní zprávu) a Solicit-response (endpoint pošle zprávu a očekává odpověď).
• binding - sváže definovaný portType s konkrétním protokolem (SOAP, HTTP, JMS) a formátem zpráv (např. Document/literal, RPC/encoded).
• port - definuje endpoint služby.
• service - množina souvisejících portů.

Sémantika verzování

Není potřeba znovu-vymýšlet-kolo. Archetypem verzování je formát <major>.<minor>.<micro>. U služeb nás micro verze nebude moc zajímat - je vyhrazená pro implementační změny, které neovlivňují vyšší řády verze a nijak se tedy nepromítají do kontraktu. minor verze je vyhrazená pro změny rozhraní, které jsou zpětně kompatibilní. No a major verze indikuje změnu rozhraní, která není zpětně kompatibilní, tj. rozbíjí kontrakt.

Změny, které jsou zpětně kompatibilní:

• přidání nové operace do služby,
• přidání nového XML typu do schématu.

Změny, které nejsou zpětně kompatibilní:

• odebrání operace ze služby,
• přejmenování operace,
• změna XML typů a atributů zprávy,
• změna namespace.

Jak?

Jako best-practice se uvádí, že verzování by pro konzumenty mělo být explicitní, tj. uvádět číslo verze v elementech, URL apod. Co všechno v kontraktu verzovat, může být předmětem diskuzí na konkrétním projektu a technologiích, nicméně dá se vyjít z těchnto pravidel:

1. Vkládat major a minor verzi do názvu WSDL souboru: MyService-v1.2.wsdl.
2. Vkládat major verzi do targetNamespace WSDL souboru:
   <definition
     targetNamespace=
         "http://sw-samuraj.cz/ws/MyService-v1"
     xmlns="http://schemas.xmlsoap.org/wsdl/">
3. Vkládat major a minor verzi do portType elementu:
   <portType name="MyServicePort-v1.2">
4. Vkládat major a minor verzi do service elementu:
   <service name="MyService-v1.2">
5. Vkládat major verzi do endpointu služby:
   <soap:address
     location=
       "http://sw-samuraj.cz/myService/v1"/>

Pokud bychom si ukázali celé WSDL, vypadalo by takto:

<?xml version="1.0" encoding="UTF-8"?>
<definitions
  targetNamespace=
      "http://sw-samuraj.cz/ws/MyService-v1"
  xmlns="http://schemas.xmlsoap.org/wsdl/"
  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">

  <types>
    <xsd:schema
      targetNamespace=
            "http://sw-samuraj.cz/ws/MyService-v1">
      <!-- schema omitted -->
    </xsd:schema>
  </types>

  <!-- messages omitted -->

  <portType name="MyServicePort-v1.2">
    <!-- operations omitted -->
  </portType>

  <!-- binding omitted -->

  <service name="MyService-v1.2">
    <port binding="MyServiceSOAP"
          name="MyServiceSOAP">
      <soap:address
        location="http://sw-samuraj.cz/myService/v1"/>
    </port>
  </service>

</definitions>

Závěr

Verzování poměrně úzce souvisí s dalším SOA governance aspektem a sice životním cyklem služeb (což je téma, na které se podíváme někdy příště). To že držíme na prostředí (typicky produkci) více verzí jedné služby má samozřejmě svoje náklady a ideálním stavem je, když služba běží pouze v jedné (nejaktuálnější) verzi.

Se správou více verzí nám může pomoci vhodný nástroj - SOA governance repository, která drží o konrétní verzi služby různá meta-data a mmj. také to, v jaké životní fázi se služba nachází, nebo kdo ji konzumuje (a koho musíme notifikovat o penzionování služby).

Architektonické principy RESTu

Jedním ze zdrojů, který jsem použil jako přípravu na certifikaci Java EE 6 Web Services Developer (o které jsem psal nedávno), je kniha RESTful Java with JAX-RS od Billa Burkeho. Bill je určitě vhodným autorem, poněvadž byl/je leaderem projektu RESTEasy od JBossu, což je certifikovaná implementace JAX-RS.

Co se týká knihy, můžu ji doporučit. Je dobře napsaná, Bill nijak netlačí svoje RESTEasy, ale objektivně zmiňuje i další alternativy - referenční implementaci Jersey a Apache CXF. Mě osobně trochu mrzelo, že celá druhá polovina knihy je workbook, jakýsi guide k příkladovému projektu - přece jenom, jak se pohybuju v architektonických sférách, tak to pro mne není až tak přínosný. Nicméně někomu jinému může tato "konrétně implementační" část pomoci dostat se (rychleji) do problému.

Ohledně RESTu jsem byl, až do přečtení knihy, panensky nepoznamenán. Teoreticky již nyní mám načteno (i z jiných zdrojů), ovšem RESTový projekt, který by mne pokřtil ohněm, mě teprve čeká. (To že jsem jednou restovou architekturu navrhl v nabídce, se nepočítá) V tomto postu (aby mi něco z toho v hlavě zůstalo) bych se zaměřil na to, co pro mne bylo nejpřínosnější a nejzajímavější: zcela jednoznačně to jsou architektonické principy RESTu.

Že termín representational state transfer pochází z dizertačky Roye Fieldinga (2000), bylo na webu napsáno již milionkrát, takže to tady nebudu omílat a skočím rovnou rovnýma nohama do principů, na kterých stojí.

Adresovatelnost

Celý REST se točí kolem zdrojů (resources). Každý takový zdroj by měl být dosažitelný pomocí jedinečného identifikátoru (URI). Tohle je celkem jednoznačný u dokumentů, aplikací a služeb. Ale když vezmeme v potaz např. Java objekty deployované na aplikačním serveru, tak u nich chybí jednotný/jednoznačný způsob identifikace, který se navíc bude lišit podle různých implementací/dodavatelů (např. JNDI).

Pro identifikaci zdroje se používá URI, které má standardizovanou podobu:

• scheme://host:port/path?queryString#fragment

přičemž scheme je protokol (např. HTTP), host je DNS nebo IP adresa, port je... port, path je virtuální hierarchická struktura, queryString je množina párů klíč=hodnota, oddělených znakem & a fragment je identifikátor, který označuje nějakou část zdroje (např. nadpis nebo obrázek v dokumentu).

Jednotné rozhraní

Tak jako se REST točí kolem zdrojů, tak se také točí kolem HTTP, jehož jednotlivý metodám připisuje specifický účel a význam.

• GET je určena pro read-only operace, jako je načtení seznamu zdrojů (dokumentů), nebo obsahu jednoho zdroje. Je jednak idempotentní (lze ji volat opakovaně se stále stejným výsledkem) a jednak bezpečná (safe, nezpůsobuje žádné vedlejší efekty).
• PUT umožní daný resource (tělo zprávy/requestu) uložit na serveru na určitém URL. Předpokládá, že klient zná potřebný identifikátor. Metoda je idempotentní, technicky bývá implementovaná jako insert nebo update.
• DELETE odstraní daný resource. Je idempotentní.
• POST je funkčně hodně podobná metodě PUT. Zásadní rozdíl je, že je to jediná metoda která není idemopotentní. Čili s každým dalším requestem měním stav daného zdroje/služby.
• HEAD je podobná metodě GET, s tím rozdílem, že response nevrací body, ale pouze response code a HTTP hlavičky.
• OPTIONS vrací komunikační možnosti a schopnosti serveru pro dané URI.

Orientace na reprezentaci

Při komunikaci pomocí HTTP metod dostáváme a posíláme na dané URI nějakou reprezentaci zdroje. Podle toho, čím je daný zdroj reprezentován, tak dostáváme/posíláme XML, JSON, YAML apod.

Metodou GET například můžu z nějakého URI dostat takovouto reprezentaci:

<product id="42">
    <name>Kindle Touch</name>
    <currency>USD</currency>
    <price>139</price>
</product>

Pokud bych chtěl zdroj na serveru změnit, pak pošlu metodou PUT (nebo POST) na stejné URI následující reprezentaci (změna ceny):

<product id="42">
    <name>Kindle Touch</name>
    <currency>USD</currency>
    <price>99</price>
</product>

Jestli bych použil PUT nebo POST, by záleželo na designu této služby. Obecně, protože PUT je, podle definice, idempotentní, tak se používá pro update, POST idempotentní není a používá se pro insert.

Nebo jinak definováno - s prvním PUT requestem se založí na serveru zdroj a s každým dalším stejným PUT requestem se tento zdroj aktualizuje. Pokud request obsahuje stejná data, zdroj se nijak nemění (to je ta idempotentnost). Naopak s každým POST requestem by měl na serveru vždy vzniknout nový zdroj. To v reálu často nebývá pravda - POST funguje jako update (stále stejného zdroje), což ale není čistý RESTový design.

Bezstavová komunikace

Bezstavovost znamená, že žádná klientská data nejsou spravována na serveru, tzn. žádná klientská session. Pokud aplikace potřebuje udržovat stavovost, spravuje si ji sama (jako kdyby to byl tlustý klient) a pouze propaguje na server změněné zdroje.

Mezi běžně uváděné benefity bezstavovosti patří: jednoduchost business logiky, škálovatelnost a cacheování resourců.

HATEOAS

Význam této ošklivé zkratky je Hypermedia As The Engine Of Application State. S pochopením tohoto principu jsem měl největší problém. Myšlenka je jednoduchá - datový formát, hypermedia (rošíření hypertextu), poskytuje speciální informaci, jak měnit stav zdroje. A dotaženo do konce - klient by měl komunikovat se serverem pouze pomocí hypermedia a nepotřebuje k tomu žádnou další (technologickou) informaci.

V případě webových služeb je HATEOAS přítomen v podobě odkazů uvnitř (XML/JSON) dokumentů, které představují zdroje. U XML dokumentů se pro odkazy často používá specifikace Atom a z ní konkrétně element link.

<product id="42">
    <link rel="self"
          href="http://amazon.com/product/42"
          type="application/xml"/>
    <link rel="payment"
          href="http://amazon.com/checkout/42"
          type="application/xml"/>
    <name>Kindle Touch</name>
    <currency>USD</currency>
    <price>139</price>
</product>

Jak pojmenovávat jednotlivé relace uvnitř odkazů je částečně standardizováno, takže se používají např. následující (samopopisná) jména: chapter, edit, first, icon, last, next, payment, previous, self, stylesheet ad.

Zamyšlení

Musím přiznat, že v rámci teoretického načtení, se mi RESTová architektura hodně líbí, zejména svojí čistotou a jednoduchostí. Je otázka (času), jak se tento můj pohled změní při použití RESTu v praxi. Tu praxi, bohužel, zatím vidím na nějaký menší projektík, protože jak se poslední dobou věnuju SOA v enterprise sféře, tak musím konstatovat, že REST je v této oblasti opomíjen jak dodavateli řešení, tak zákazníky. Ale snad se časem začne blýskat na lepší časy.

Certifikace Java EE 6 Web Services Developer

Tak nějak jsem si poslední dobou zvykl, dělat do roka dvě certifikace (asi mi chybí školní dril :-) Takže co to bylo tentokrát? Honosný název, který se nyní skví v mém CV zní: Oracle Certified Expert, Java Platform, Enterprise Edition 6 Web Services Developer, zkráceně (ve stylu někdejších Sunovských certifikací) OCWSD.

Certifikace občas budí (zbytečné) vášně, takže základní otázka asi je: je to vůbec k něčemu? Pro mne je tím největším benefitem, že jsem se něco nového (do hloubky) naučil. A musím říct, že OSWSD je tomto směru opravdu hodnotná. Byť web servisy mastím cca poslední tři roky, ať už v Javě (JAX-WS, Spring WS nebo Axis), nebo v rámci SOA (WebSphere Message Broker, Oracle SOA Suite), tak během přípravy na certifikaci jsem dozvěděl spoustu nových věcí (třeba SOAP Message Handlers) a "dopochopil" lecos již známého.

Témata, která zkouška obsahovala jsou následující:

• Create an SOAP web service in a servlet container
• Create a RESTful web service in a servlet container
• Create a SOAP based web service implemented by an EJB component
• Create a RESTful web service implemented by an EJB component
• Configure JavaEE security for a SOAP web service
• Create a web service client for a SOAP based web service
• Create a web service client for a RESTful web service
• Create a SOAP based web service using Java SE platform
• Create handlers for SOAP web services
• Create low-level SOAP web services
• Use MTOM and MIME in a SOAP web service
• Use WS-Addressing with a SOAP web service
• Configure Message Level security for a SOAP web service
• Apply best practices to design and implement web services

Protože na zkoušku není žádný oficiální certifikační guide, prošel jsem trošku širší okruh materiálů. V praxi jsem zatím neměl nikdy možnost dostat se k RESTovým technologiím, takže jsem s předstihem začal s knížkou Billa Burkeho RESTful Java with JAX-RS, kterou vřele doporučuji - pokud chcete začít s RESTem v Javě (tj. libovolnou implementací JAX-RS), je to ta správná volba. Autor sice popisuje (a je tvůrcem) RESTEasy, ale je objektivní i vůči dalším implementacím.

Další knihou jsem si chtěl oživit druhou Javovskou web servisovou větev - JAX-WS. Tady je knižní situace docela slabá. V podstatě jediná aktuální kniha, která je věnována JAX-WS je Java 7 JAX-WS Web Services. Vzhledem k názvu a rozsahu (64 str.) jsem nečekal nic světoborného, ale zklamání bylo obrovské. Pokud nejste úplně nejzelenější začátečník a nevyhovují vám knížky, tvořené ze 2/3 screenshoty (NetBeansů), není to kniha pro vás. Škoda peněz, škoda času.

Jakou určitý druh přípravy můžu zmínit (celkem nudný) letošní Oracle Java Developer Day, kde jsem se šel podívat na jednu přednášku o JAX-WS a na dvě o JAX-RS. Samozřejmě, že to byly naprosté základy, ale člověk si aspoň udržuje povědomí o tématu.

Pak už začalo jít do tuhého, protože jsem potřeboval něco, co by mě připravilo na certifikaci. Nechal jsem tedy firmu zakoupit zkušební testy. Tentokrát jsem zvolil ještě nevyzkoušené řešení - kit od EPractize Labs. Jejich OCEJWSD Training Lab není úplně špatný. Sice je uživatelsky dost nepohodlný a rozložení témat mi přijde dost nevyvážené, ale myslím, že ho můžu označit jako přínosný. V dnešní době bych spíš volil kit od uCertify, s jejichž přípravnými testy mám dobrou zkušenost, který ale v té době ještě nebyl k dispozici.

Posledním materiálem, který jsem na přípravu použil je OCWSD Study Guide od Mikalaie Zaikina, který pokrývá témata zkoušky velmi pěkně. Linkovaná webová verze je zdarma, za $15 je možné si přikoupit sadu 160 otázek s odpověďmi, plus jednotlivé guidy v PDF podobě. Těch patnáct dolarů jsem investoval a můžu říct, že to stálo za to (aneb jak jsme se učili v angličtině it bang for the buck).

Pokud mám certifikaci OCWSD nějak celkově zhodnotit, musím říct, že je to určitě jedna z těch nejpřínosnějších, co dnes Oracle v oblasti Javy nabízí. Všechna témata byla víceméně ryze praktická, žádná nudná (korporátní) teorie, či dokonce ideologie. Zároveň je to taky jedna z těch, kde je těch Oraclovských technologií jen určité minimum - hodně se tam probírají věci z W3C, jako je SOAP, WSDL, XSD, WS-Addressing, nebo věci, které jsou dílem různých jiných organizací, jsou je WS-I (WS-Interoperability (Basic Profile)), nebo WS-Security.