Dostupné sekce

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.

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.

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ů.

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>
            

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.

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.

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.

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".

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:

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.