Nové REST rozhraní - migrace a seznam změn

Na seznam témat a kapitol (obsah)Nadřízená kapitola

Jak je uvedeno v kapitole o starém REST rozhraní, v říjnu 2018 došlo k velké modernizaci modulu webových služeb, při které došlo k mnoha změnám. Následující sekce popisují všechny změny, které v rámci modernizace nastaly a uvádějí informace o tom, jak přemigrovat klienty webových služeb na nové rozhraní:

SOAP je beze změn

SOAP rozhraní je bez jakýchkoliv změn v okamžiku, kdy webová služba probíhá bez problému.

Jediný zaznamenaný rozdíl nastává v okamžiku, kdy při zpracování webové služby dojde k chybě. V okamžiku, kdy služba vrací z jakýchkoliv důvodů SOAP:Fault, byly revidovány různé důvody a upraveny návratové hodnoty chyb (například byly udělány změny v tom, "čí je to chyba", typicky faultcode byl v případě nevalidního vstupního XML změněn na "soap:Client" a podobně). V případě normálního běhu služeb se však nezměnilo nic.

13 měsíců kompatibility

Staré REST rozhraní na URL

/ws/service/rest

bude udržováno do 31.12.2019. Pak bude nenávratně zrušeno. Předpokládáme, že je to dostatečná doba na zkontrolování klientských aplikací, případně provedení úprav popsaných dále. Poté, co své aplikace upravíte, upravte URL na

/ws/service/rest2

, kde jsou všechny dosavadní služby publikovány stejným způsobem (tj. na adekvátních URL se stejným způsobem předání parametrů - až na výjimky, viz dále).

Webové rozhrané pro volání služeb

Webové rozhraní pro volání služeb, které je dostupné na záložce "Spouštění služeb", bude až do 31.12.2019 pracovat nad původním REST rozhraním. Následně dojde k přepnutí této nadstavby nad nové REST rozhraní.

Specifikace požadovaného výstupního formátu

Ve starém REST rozhraní se k určení požadovaného výstupního formátu používal speciální parametr "outputFormat", který šel přidal k mnoha službám. Tento parametr je pro snadnost přechodu zachován, nicméně doporučujeme přejít na nový způsob určení toho, jaký výstupní formát chcete a to použitím hlaviček v HTTP požadavku. Využívejte hlavičku Accept, v níž můžete formátů uvést i více za sebou se specifikací Vašich prefencí.

Hlavičkou Content-Type naopak říkáte, jaká data na server nahráváte. To je samozřejmě potřeba pouze u služeb, které jsou volány HTTP metodami POST, PUT atd.

Aktualizovaný modul podporuje nově exporty do formátu YAML. Taktéž je podporován nově export do formátu XLSX. Společně s ukončením podpory starého REST rozhraní dojde k odebrání podpory starého formátu XLS.

Pozor, nová verze REST rozhraní již defaultně nevrací formát XML! Zadáte-li tedy adresu webové služby do webového prohlížeče, dostanete nejspíše chybovou hlášku typu

No message body writer has been found for class
cz.zcu.stag.services.types.common.WSStringListBean,
ContentType: text/html

či podobnou. Podstatný je onen "Content-Type: text/html" - prohlížeč totiž zasílá hlavičku "Accept" a primárně samozřejmě chce HTML stránku. Modul WS však HTML (zatím) vracet neumí a proto neumí požadovaný datový formát poskytnout.

(Ne)doporučované výstupní formáty

Pro účely napojení externích informačních systémů na IS/STAG Vám silně doporučujeme používat výstupní formáty XML, JSON, případně YAML. Naopak silně nedoporučujeme používat formáty CSV, XLS a XLSX!

Jak je uvedeno i v kapitole o výstupních datových formátech, tyto tabulkové formáty jsou určeny především pro "lidi" (tj. pro případ, kdy uživatel využívá modul WS pro export nějakých dat, na která se pak dívá v Excelu). U těchto formátů NEGARANTUJEME jejich neměnnost v čase. Zároveň je jejich generování na straně serveru neoptimalizováno a spotřebuje násobně více prostředků (čas, paměť, výkon) než výstup do doporučených formátů.

Vstupní formáty

Aplikace od října 2018 NEPODPORUJE (u žádného REST rozhraní) možnost NAHRÁVAT data ve formátech CSV/XLS (tj. zaslat vstupní parametry). Tato funkce byla možná pouze prostřednictvím webového formuláře (tj. nebyla to vlastnost samotných webových služeb, ale pouze rozhraní nad nimi vybudovaného), byla využívána naprosto minimálně a byla odebrána.

Vstupní a výstupní XML

Je rozdíl mezi starým a novým REST rozhraním u formátu XML. U starého REST rozhraní je XML vždy zabaleno do "zbytečného" ještě jednoho hlavního root elementu, například:

<stag:insertPracoviste xmlns:stag="http://stag-ws.zcu.cz/">
    <pracoviste>
        <cisloPracoviste>12345</cisloPracoviste>
        <cisloPracovisteInterni>12345</cisloPracovisteInterni>
        <zkratka>XYZ</zkratka>
        <nazev>Testovaci pracoviste</nazev>
        <nadrazenePracoviste>REK</nadrazenePracoviste>
        <typPracoviste>K</typPracoviste>
        <vedouciUcitIdno>17098</vedouciUcitIdno>
    </pracoviste>
</stag:insertPracoviste>
            

Nově je ten hlavní element, který dříve reflektoval název webové služby, odebrán. XML pak reprezentuje přímo a pouze onen datový typ, který je službě předáván (či ze služby vyzvedáván). Zároveň u některých služeb došlo ke změně názvu onoho hlavního datového typu, zde například namísto "pracoviste" je "pracovisteForEdit":

<stag:pracovisteForEdit xmlns:stag="http://stag-ws.zcu.cz/">
    <cisloPracoviste>12345</cisloPracoviste>
    <cisloPracovisteInterni>12345</cisloPracovisteInterni>
    <zkratka>XYZ</zkratka>
    <nazev>Testovaci pracoviste</nazev>
    <nadrazenePracoviste>REK</nadrazenePracoviste>
    <typPracoviste>K</typPracoviste>
    <vedouciUcitIdno>17098</vedouciUcitIdno>
</stag:pracovisteForEdit>
            

Vstupní a výstupní JSON

Ve starém modulu byly možnosti volby formátu pouze u výstupu. Při volání POST služeb se vstupními komplexními datovými typy bylo vždy nutné předat XML. Nový modul již akceptuje i na vstupu formáty JSON a YAML. (Pozor, formáty CSV a XLSX jsou opravdu speciální a jsou brány i nadále pouze jako výstupní).

U výstupu do JSON došlo ke změně, která reflektuje změnu u XML uvedenou v předchozí sekci. Dříve byl vždy celý JSON "zabalen" ještě navíc v obalovacím elementu "[" a "]" (jakoby byl celý výstup ještě navíc jako jeden prvek nějakého pole). Nově je JSON vracen "o úroveň níže", tj. není tímto root polem obalen.

HTTP kódy

V případě, že webová služba nevrací žádná data (null či prázdný seznam), nově vrací pouze HTTP kód k tomu určený: 204 No Content.

Služby se "String" výstupem

Existuje několik služeb, které vracejí pouze jediný řetězec. Jedná se například o služby getUcitIdnoByStagLogin, getExternalLoginByUcitIdno a podobné. Protože došlo k odstranění obalujícího XML elementu při výstupu dat v XML, nelze služby s takto jendoduchým výstupním datovým typem do XML vůbec převádět. Není prostě "do čeho výsledek obalit". Tyto služby proto nemají možnost výstupu do XML, musíte využít JSON a nebo službu zavolejte s "Accept: text/plain", což je nejjednodušší - výsledkem volání je prostě prostý text.

Přihlašování

Proces přihlašování je popsán v samostatné kapitole. Novinkou je to, že modul WS po úspěšném přihlášení uživatele rovnou volajícímu vrátí i nový parametr "stagUserInfo", v němž volající rovnou získá seznam uživatelských rolí toho, kdo byl právě přihlášen. Není tak pro klienta nutné rovnou okamžitě volat webovou službu getStagUserListForLoginTicket, data získá rovnou a hned.

Zároveň dojde v okamžiku ukončení podpory starého REST rozhraní k odebrání parametrů, které neměly valný význam a s přidáním nového parametru ztrácí zcela smysl - modul WS přestane předávat parametry "stagUserName" a "stagUserRoles".

Změny ve službách

V nové implementaci aplikace nebylo bohužel možno zachovat zpětnou kompatibilitu (tzn. ani ve staré, kompatibilní verzi REST rozhraní) v následujících případech:

  • studenti/zapisRozvrhovychAkci .  Struktura vstupního XML byla lehce pozměněna, došlo k "obalení" jinými XML elementy. Více viz dokumentace a WADL služby.

  • Všechny nové služby s prefixem ng_ .  Tyto služby jsou vytvářeny automaticky a bohužel nebylo možné jejich generování přizpůsobit. Struktura navráceného datového typu se bohužel lehce liší, například v případě XML je obalen novým root elementem. Změna se netýká mnoha reálně využívaných služeb, nicméně dva příklady používaných jsou: TROZ (Služby používané pro tvorbu rozpočtu na ZČU) a REDOP (služba pro výstup pro systém REDOP). Prosímte, kontaktujte správce těchto systémů, ať své klienty adaptují. Děkujeme za pochopení.

Další změny - prosím hlašte

Před nasazením modulu došlo k důkladnému testování všech služeb a v rámci tohoto testování k porovnávání starého aplikace a kompatibilního rozhraní v aplikaci nové. Testovány byly všechny výstupní formáty podporované starou aplikací (XML, JSON, CSV, XLS). Dospěli jsme k závěru, že žádné jiné rozdíly aplikace neobsahuje a tudíž že se nám podařilo vytvořit kompatibilní rozhraní tak, že až na popsané "drobnosti" (například služba, u které to bohužel vážně nešlo), je shodné s původním.

Přesto bychom velmi ocenili - jakmile narazíte na nezvyklé chování svého klienta (a tipuji, že se to určitě stane), napište nám prosím o tom hlášení na stag@service.zcu.cz a popište přesně, jaký posíláte HTTP požadavek, jak se aplikace nově chová a jak se chovala dříve. Pokusíme se na taková hlášení reagovat velmi pružně a aplikaci tak co nejdříve opravit.