Podporované standardy

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.

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.

Dostupné sekce