Podporované standardy

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

Aplikace publikuje pro klienty webové služby několika způsoby, využívá několika "standardů" (slovo "standard" není v případě REST adekvátní, protože žádný standard neexistuje, nicméně jedná se o široce uznávaný a zaběhnutý přístup).

  • Web Services prostřednictvím protokolu SOAP Běžný a léty prověřený standard, používaný typicky mezi velkými informačními systémy. Specifikace, Wikipedia, podporujeme SOAP 1.1 a WSDL 1.1. Popisy všech endpointů webových služeb jsou k dispozici ve formátu WSDL, odkazy na ně naleznete v seznamu služeb.

  • REST Rozhraní využívající protokolu HTTP a jeho vlastností - snaha o maximální jednoduchost a "přirozenost" přístupu k údajům, kterou splňuje myšlenka webových služeb podle REST (Wikipedia). Popisy všech endpointů webových služeb jsou k dispozici ve formátech WADL a experimentálně i ve formátu OpenAPI (původně Swagger), odkazy na ně naleznete v seznamu služeb.

  • REST - "staré" rozhraní V říjnu 2018 byla provedena velká modernizace modulu WS a rozhraní REST, které fungovalo 10 let, bylo označeno za zastaralé a nahrazeno novým REST rozhraním. Nové REST rozhraní se liší především v možnostech do budoucna. Popisy endpointů webových služeb tohoto starého rozhraní nejsou k dispozici v žádném ze strojově čitelných formátů. Toto staré REST rozhraní bude výhledově zcela zrušeno, viz informace v příslušné kapitole.

SOAP Web Services

SOAP rozhraní sídlí na URL adresách s cestou začínající

/ws/services/soap

U tohoto rozhraní není příliš mnoho co popisovat. Jsou k dispozici kompletní WSDL soubory s popisy rozhraní, na jejichž základě lze nechat vygenerovat klienty či například testovat volání služeb nástrojem SoapUI. Pro testování lze využít například jednoduché služby pro evidenci místností:

https://stag-demo.zcu.cz/ws/services/soap/mistnost?wsdl

NENÍ využito rozšíření WS-Security (ani jiné WS-* rozšíření). Pro přenos přihlašovacích údajů (viz kapitola o ověřování uživatelů) je využito možností protokolu HTTP(S) - konkrétně se využívá klasická metoda HTTP BASIC.

REST rozhraní

Toto REST rozhraní sídlí na URL adresách s cestou začínající

/ws/services/rest2

U aktuálního REST rozhraní jsou k dispozici specifikace v jazyce WADL, experimentálně se brzy objeví i možnost stažení popisu rozhraní ve formátu OpenAPI (dříve známý jako Swagger).

https://stag-demo.zcu.cz/ws/services/rest2/ciselniky?_wadl

Vstupní formát dat (jsou-li nějaká data jako vstup zasílána) je určen použitím HTTP hlavičky "Content-Type". Očekávaný výstupní formát (či více podporovaných výstupních formátů v pořadí priorit) určuje klient zasláním HTTP hlavičky "Accept". Pro zachování části kompatibility s původním "starým" REST rozhraním je i nadále podporována možnost zaslání query parametru s názvem "outputFormat", jehož hodnota může být jedna z hodnot: XML, JSON, CSV, XLS, XLSX, ICS, ICAL, YAML. Příklad takového volání:

https://stag-demo.zcu.cz/ws/services/rest/ciselniky/getCiselnikNewItems?domena=ANO_NE&outputFormat=JSON

Oproti starému REST rozhraní je významně více využíváno možností protokolu HTTP. Příkladem jsou zmíněné hlavičky "Content-Type" a "Accept", dále pak využívání návratového HTTP kódu. 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.

Z tohoto důvodu si dávejte pozor při testování REST služeb voláním pouze z internetového prohlížeče. Ten defaultně zasílá hlavičku (například Chrome) Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8 a tudíž preferuje nejdříve HTML a pak XML verze dat. Mnohé webové služby ale tomuto nemohou dostát a testování z prohlížeče se tudíž nemusí dařit tak, jako dříve.

Interně je rozhraní vybudováno s využitím specifikace JAX-RS.

"Staré" REST rozhraní

Toto REST rozhraní sídlí na URL adresách s cestou začínající

/ws/services/rest

V říjnu 2018 byla provedena velká modernizace modulu WS. Rozhraní REST, které fungovalo 10 let, bylo označeno za zastaralé a nahrazeno novým REST rozhraním. Není technicky možné jej udržovat a především rozvíjet i nadále.

Původní (staré) REST rozhraní bude udržováno po dobu cca JEDNOHO ROKU od zveřejnění nového rozhraní. Oznámení o definitivním ukončení podpory starého REST rozhraní bude s dostatečným předstihem uvedeno v seznamu změn modulu webových služeb a bude zasláno i do mailing listu.

Předpokládaný termín ukončení běhu starého REST rozhraní je 31. 12. 2019.

Nové REST rozhraní v základu zcela přesně kopíruje URL, adresy, použité parametry i významy původního REST rozhraní. Samotné webové služby a jejich funkcionalita nebyla změněna, došlo pouze ke změně rozhraní jejich volání. Změna rozhraní byla nutná pro udržitelnost do budoucna a také pro zjednodušení celého konceptu. Přečtěte si prosím průvodce migrací na nové REST rozhraní, kde je uveden kompletní a detailní seznam změn, které je nutno při přechodu na nové REST rozhraní respektovat.