Webové služby - technické informace

Změny a novinky

Od října 2014 existuje mailová konference stag-ws@list.zcu.cz, do které je možné se zaregistrovat (viz níže) a získávat tak e.maily při vydání každé nové verze aplikace webové služby a zároveň i v případech, kdy vývojáři IS/STAG potřebují dopředu upozornit na budoucí změny. Všem, kteří rozhraní webových služeb nad IS/STAG využívají ve svých aplikacích doporučujeme se do této konference zaregistrovat:

  • E-mailová adresa konference: stag-ws@list.zcu.cz
  • Veškeré informace o konferenci jsou k dispozici zde (včetně možnosti přihlášení): Informace o konferenci
  • Po přihlášení a potvrzení e-mailové adresy budete dostávat informace o změnách modulu webových služeb

V této sekci se budou objevovat informace o důležitých změnách v aplikaci, především o změnách ve formátech dat používaných webovými službami: Seznam změn v aplikaci WS.

Použité standardy

  • SOAP: Na jedné straně stojí požadavky na propojení IS/STAG s dalšími počítačovými systémy, pro což je potřeba řekněme jednoho z nejpropracovanějších standardů - Web Services dle W3C (Specification, Wikipedia).
  • REST: Na druhé straně stojí ale snaha o maximální jednoduchost a "přirozenost" přístupu k údajům (žádné SOAP, WSDL, ...), kterou splňuje myšlenka webových služeb podle REST (Wikipedia).
Podporované standardy jsou:

Použitý framework (s mnoha úpravami): Apache CXF 2.0.9.

Poskytované služby

Aktuální seznam poskytovaných služeb je k dispozici jako jako další záložka tohoto dokumentu a je automaticky aktualizován při jakýchkoliv změnách (je automaticky generován serverem).

Většina služeb je poskytována jak ve formě "SOAP" i "REST". Následuje popis jednotlivých informací, které jsou o každé službě, jejích operacích (metodách) a parametrech metod k dispozici:

  • Služby
  • Typ Typ této služby - SOAP či REST
    Adresa Adresa, na níž je služba k dispozici
    WSDL Adresa WSDL specifikace této služby. WSDL je k dispozici pro oba typy služeb
    Popis, Popis EN Český a případně anglický popis
  • Operace
  • Název Název operace, například "getStudentiByPredmet"
    HTTP metoda předání parametrů GET či POST - udává HTTP metodu, kterou se (v případě REST služby) předávají vstupní parametry. Obvykle u jednoduchých parametrů je GET, u složitějších či zapisovacích bývá POST. V případě POST se pak předávají parametry ve formě XML metodou POST, formát XML je uveden ve WSDL specifikaci služby.
    Vrací obecný (binární) výstup? Pokud je false, jedná se o klasické služby. Pokud je true, jedná se o zcela speciální služby, které víceméně neodpovídají standardu Webových služeb, protože jsou to služby, které vrací zcela obecný (binární) výstup. Čili nemají žádné WSDL, protože vůbec nemusejí vracet XML. Příkladem může být služba, která vrací obsah diplomové práce. Takové služby jsou přístupné pouze přes REST rozhraní, nikoliv přes SOAP.
    Je nutné ověřování Zda je nutné ověřování identity uživatele (tj. zda je požadováno přihlášení, viz. kapitola o ověřování)
    Je nutné HTTPS? Udává, zda je nutné připojení přes HTTPS. Obvykle souvisí s předchozím údajem. Pozor, je-li údaj 'false', neznamená to, že je služba nutně přístupná přes HTTP. Správce serveru může zveřejnit všechny služby pouze přes HTTPS (což se doporučuje). Parametr pouze zesiluje zabezpečení tak, že některé služby MUSÍ být zabezpečeny POUZE protokolem HTTPS.
    Povolené role Seznam STAGovských rolí, které mohou danou službu volat. Týká se jen služeb s ověřováním a označuje role, které mohou službu použít. Může mít hodnoty "ST" (student), "VY" (vyučující), "KA" (katedra), "FA" (tajemník fakulty) a další dle interní specifikace STAGu. Hodnota "ALL" znamená, že službu může volat uživatel s jakoukoliv IS/STAG uživatelskou rolí - na konkrétní roli však záleží a je třeba aby byla specifikována. Oproti tomu hodnota "LOGGED" znamená, že službu může volat zcela libovolný přihlášený uživatel a je úplně jedno, jakou a zda vůbec má nějakou IS/STAG roli.
    Expire time (sec) Čas v sekundách, udávající platnost výstupu této operace. Tato hodnota se vrací v HTTP odpovědi klientovi a má sloužit k tomu, aby si klient uložil výstup do své vyrovnávací paměti. Obvykle také slouží k orientaci, jak často se data daného typu asi tak v databázi mění. Viz také kapitola o cachování.
    Komentář Informace o operaci.
    XML typ výstupu (viz. WSDL) Název XML typu výstupu operace - odkazuje na typy definované v XML schématu ve WSDL této služby.
  • Parametry operací
  • Název Název parametru
    Typ (Java) Typ parametru tak, jak je použit v programovacím jazyce Java (slouží spíše pro představu). XML typ parametru je uveden ve WSDL.
    Povinný? Udává, zda je parametr povinný, tj. zda-li musí být uveden. Pokud není, je mu dosazena příslušná default hodnota (viz. kapitola o častých parametrech). Toto se týká především volání REST metodou GET, kde lze některé parametry vynechat. Při volání přes SOAP či metodou POST se doporučuje uvádět všechny parametry s tím, že některé mohou mít hodnoty 'null'.
    Username uživatele? Udává, zda se jedná o parametr, jehož hodnota musí být vždy shodná se jménem ověřeného uživatele. Další info viz. kapitola o ověřování.
    Komentář Popis parametru.

SOAP Webové služby

Tento typ webových služeb je určen pro komunikaci s jinými počítačovými systémy třetích stran. Specifikace je zaměřená na to, aby bylo možno strojově vytvářet klienty a volat služby "bez znalosti dokumentace" (v uvozovkách je tato formulace schválně, platilo by za ideálních podmínek v oblasti softwaru :-) ). V každém případě služby jsou přesně definovány pomocí WSDL, které slouží každé službě jako vstupní bod a jehož znalost je pro komunikaci potřeba.

Pro vyhledávání služeb není (zatím) zprovozněna žádná vyhledávací služba (např. UDDI). Seznam poskytovaných webovských služeb (odkaz viz pravý horní roh tohoto dokumentu) obsahuje adresy všech WSDL a je tedy možno je najít tímto způsobem.

Popis práce s WebServices, popis WSDL či SOAP je již nad rámec této dokumentace, zájemce ale odkazuji například na stránky Wikipedie, kde najdou další odkazy na různé frameworky a řešení hotová pro čtenářův oblíbený programovací jazyk. Zajímavým testovacím prostředkem jsou různí univerzální SOAP klienti, doporučuji například aplikaci SoapUI. Dále je možno čtenáře odkázat na kapitolu obsahující ukázkové klienty STAG webových služeb.

Webové služby podle REST

Oproti konceptu W3C WebServices jsou Webovské služby podle REST jednoduché - neobsahují žádné SOAP (protokol pro přístup ke vzdáleným objektům), požadavky nejsou zdaleka tak zaobalené do XML. Zatímto SOAP typ je zaměřen spíše na přístup k operacím vzdáleného systému, REST pohlíží spíše na data takového systému. Centrem pohledu REST jsou data - data mají svojí URL adresu.

Tento zásadní rozdíl je velmi výhodný v situacích, kdy chceme ze STAGu získat údaje tak, jako to lze například prostřednictvím portálu a portletu "Prohlížení". Stačí znát příslušnou URL a na ní nám Webovské služby přímo poskytnou XML s požadovanými daty. Výsledné XML lze pak snadno transformovat například na XHTML a přímo zobrazit na webovské stránce či s daty dále pracovat.

REST adresa požadovaných dat vypadá následovně:

 http://stag-ws.zcu.cz/ws/services/rest/student/getStudentiByPredmet?katedra=KIV&predmet=DTP1&rok=2004&semestr=LS

Jednotlivé části adresy:

  • http://stag-ws.zcu.cz/ws/services/ - Základní URL Webovských služeb
  • rest/student/ - adresa konkrétní služby
  • getStudentiByPredmet - název metody, která data získá (stejná jako v případě SOAP)
  • ?katedra=KIV&predmet=DTP1&rok=2004&semestr=LS - parametry této metody

Jinými slovy, pokud si odmyslíme, že se v URL vyskytuje název metody (operace), která data získává, jedná se o adresu, která (pomocí parametrů) přesně říká o jaká data má klient zájem. Připojíte-li se na tuto adresu, získáte výstup jako v případě SOAP, jen bez obalujícího SOAP:

<ns1:getStudentiByPredmetResponse xmlns:ns1="http://stag-ws.zcu.cz/">
  <studentiPredmetu>
    <studentPredmetu>
      <osCislo>A02196</osCislo>
      <jmeno>Lukáš</jmeno>
      <prijmeni>BALINT</prijmeni>
    </student>
    <student>
      <osCislo>A04504</osCislo>
      <jmeno>Jan</jmeno>
      <prijmeni>BÁRTA</prijmeni>
      <titulPred>Bc.</titulPred>
    </studentPredmetu>
    .
    ..
    ...
    ..
    .
  </studentiPredmetu>
</ns1:getStudentiByPredmetResponse>

Přesné schéma tohoto výstupního XML je vždy stejné jako v případě SOAP volání téže webové služby a je definována ve WSDL souboru dané služby. Typicky obsahuje nějaký základní XML element (odpovídající názvu volané operace) a poté již XML reprezentaci návratového datového typu.

Formáty dat

Je podporována přímá podpora pro konverze do dalších formátů pro výměnu dat a to přímo zadáním specifického parametru v URL REST webových služeb. Jedná se POUZE o EXPORT dat z IS/STAG, nikoliv o konverzi při jejich nahrávání do IS/STAG metodou POST (tuto možnost má pouze formulářové webové rozhraní, nikoliv však samotné webové služby). Výchozí formát, kterým jsou výstupy předávány z Webových služeb (XML) lze tak nahradit následujícími formáty:

  • XLS - Formát programu Microsoft Excel pro uložení tabulek. Lze tedy přímo otevřít v Excelu. Tento formát je doporučen pro komunikaci s tímto programem.
  • CSV - Jednoduchý textový formát pro uložení tabulkových dat. Tento formát lze také otevřít v Excelu, avšak mohou s ním nastat některé problémy. Například s kódováním znaků s diakritikou či s datumy a časy. Protože je nyní implementován přímo formát XLS, ztrácí formát CSV svůj význam.
  • JSON - Pro použití například přímo z javascriptových programů.
  • ICS - Formát pro uložení kalendářových dat - iCal, přípona ICS. Všechny webové služby pro rozvrhy, či služby pro harmonogram akademického roku mají svoji alternativní webovou službu, jejíž název je zakončen písmeny "ICAL". Tyto služby vracejí svůj výstup přímo ve formátu ICS, lze si tedy okamžitě a přímo importovat například svůj rozvrh do aplikací Outlook, Google Calendar a dalších...

    Poznámka: Zmíněné webové služby vracejí formát ICS přímo, není tedy nutné (a ani to nelze použít) zapisovat níže zmíněné parametry.

K URL dané webové služby (jedná se o REST webové služby) je potřeba přidat jeden či dva parametry:

  • outputFormat Určuje požadovaný formát výstupu, tedy např. XLS či CSV
  • outputFormatEncoding Určuje požadované kódování výstupu. Má význam pouze u exportu do formátu CSV. Není-li při exportu do CSV uvedeno, použije se kódování 'windows-1250', které má většina lidí nastaveno v Excelu jako výchozí.

Příklady jsou uvedeny přímo na titulní stránce Vítejte.

Zabezpečené operace - ověření uživatele

Některé služby obsahují údaje, které nejsou k dispozici veřejnosti, ale pouze oprávněným uživatelům. Fakt, zda daná služba potřebuje ověření, je uveden v nápovědě u konkrétní operace (ověření je až na úrovni operací, nikoliv celých služeb). Klient se pak musí ověřit standardním mechanismem HTTP BASIC a to (ve výchozím nastavení) svým STAGovským uživatelským jménem a heslem (studenti tedy osobním číslem, učitelé zpravidla svým loginem). Takové služby lze také volat pouze přes zabezpečenou vrstvu HTTPS.

U zabezpečených služeb se často objevuje jméno uživatele také jako parametr (stagUser) vlastní volané operace - tedy uživatel chce například znát své osobní údaje - zavolá operaci "getOsobniUdaje", jejímž parametrem je jeho STAG uživatelské jméno. Systém po něm bude chtít ověření (prohlížeč zobrazí výzvu pro zadání hesla). Zároveň ale musí platit podmínka, že uživatel buď tento parametr (stagUser) nesmí zasílat ve vstupu (tj. ani v SOAP vstupním XML, ani v parametrech zapsaných v adrese metodou GET) a nebo jej uvede, ale v tom případě musí uvést IS/STAG uživatelské jméno, které má oprávnění použít. Nejlepší rada je tedy parametr 'stagUser' vůbec neuvádět, server si jej doplní sám podle toho, jaký uživatel se přihlásil.

V případě použití jiného ověřování než vůči IS/STAG (např. na Západočeské Univerzitě ověřování ORION identitou) může být potřeba parametr 'stagUser' uvádět tehdy, kdy má přihlášený ORION uživatel více rolí v IS/STAG a při volání konkrétní služby není jednoznačně jasné, která z rolí má být použita.

V nápovědě jsou takové parametry označeny jako "Username uživatele", vždy se jmenují "stagUser".

Detailní proces přihlášení, připojení externích systémů

Při návrhu serveru bylo počítáno s možností externích systémů (programů, klientů, webů, ...), které budou chtít webové služby využívat. Pokud by tito klienti chtěli používat i zabezpečené služby, museli by sami implementovat nějaké rozhraní s přihlášením, ověřením vůči STAGu atd. Zároveň by ale nutili uživatele, aby se přihlašovali na různých místech - a poskytovali své přihlašovací údaje různým, potencionálně nezabezpečeným a nedůvěryhodným webům.

Proto byl navržen mechanismus umožnující centralizované přihlášení, které by proběhlo na jediném místě - na důvěryhodném serveru webových služeb - a které by po úspěšném přihlášení předalo identifikační údaje uživatele zpět klientovi (programu, webu...). Odpadla by tak nutnost, aby uživatelé zasílali svá hesla na nedůvěryhodná místa.

Mechanismus je velice podobný jako systém používaný pro jednotné přihlášení na ZČU WebAuth - jedná se vlastně o jeho zjednodušenou verzi.

Každá služba, která je zabezpečena (tj. není veřejně přístupná) požaduje ve svém HTTP požadavku identifikační údaje o uživateli metodou HTTP BASIC, jak bylo uvedeno v předchozí kapitole. Jaké tyto údaje mohou být? :

  • Klasicky - uživatelské jméno a heslo: Klient může poskytnout službě své uživatelské jméno a heslo, klasicky dle specifikace zakódované do HTTP hlavičky. Tato možnost je určena především pro "lidské" klienty, kteří používají WWW prohlížeč a zadají adresu služby. Prohlížeč jim zobrazí okno požadující autorizaci, oni zadají své STAG údaje a služba je pak již ověří a vrátí svůj výstup.
  • Uživatelův ticket: Jako uživatelské jméno lze také uvést tzv. ticket uživatele, heslo je v tomto případě ignorováno (lze uvést cokoliv, i prázdné heslo). O tom, jak získat ticket uživatele viz. dále.

Kromě HTTP BASIC autorizace podporují webové služby ještě jednu možnost - ověření pomocí COOKIES. Toto ověření pomocí COOKIES je dokonce prováděno jako první. V požadavku se může vyskytovat speciální COOKIE, jehož název a doménu lze nakonfigurovat v konfiguračním souboru serveru Webových služeb. Aktuálně použité hodnoty:

  • Název cookie = WSCOOKIE
  • Doména cookie = stagservices.upol.cz

Pokud toto cookie obsahuje platný ticket uživatele, je uživatel ověřen z cookie bez nutnosti HTTP BASIC autentizace.

Ticket uživatele je jedinečný dlouhý řetězec, který je vygenerován po úspěšném přihlášení uživatele na serveru webových služeb. Ticket má časově omezenou platnost (aktuálně nastavená: 60 minut), tj. pokud není po tuto dobu použit pro volání nějaké služby, je zneplatněn. Jak lze takový ticket získat?

Programujete-li klienta (řekněme, že se jedná o nějaká nadstavbové stránky) webových služeb, postupujte takto:

  1. Po připojení uživatele na Váš web zjistíte, že se jedná o nového uživatele a že je potřeba ho přihlásit. Řekněme, že Váš web má adresu http://www.stag-client.cz
  2. Přesměrujete uživatele na server webových služeb na jeho přihlašovací stránku. Máte dvě možnosti - buď chcete nechat uživatele ověřit klasickou HTTP BASIC autorizací (přohlížeč zobrazí okýnko s přihlášením) a nebo můžete využít stránky s přihlašovacím formulářem - s nápovědou, designem atd. - doporučuji použít tuto druhou možnost. Na jakou adresu tedy můžete uživatele přesměrovat:
    • HTTP BASIC Ověření: https://stagservices.upol.cz/ws/login?originalURL=http://www.stag-client.cz&basic=1
    • Formulářové ověření: https://stagservices.upol.cz/ws/login?originalURL=http://www.stag-client.cz

    Pozor, adresy uvedené v "originalURL" musí být zakódované pro použití v URL, zde jsou uvedeny z důvodu čitelnosti. Ve skutečnosti bude adresa zakódovaná do URL vypadat takto: " ...?originalURL=http%3A%2F%2Fwww.stag-client.cz " !

    Serveru tedy dáváte informaci o tom, z jakého URL je jeho přihlašovací služba požadována - že je požadována od Vás a server tak ví, kam poté uživatele "vrátit".

  3. Nyní je práce na straně serveru webových služeb, který uživatele nechá přihlásit. Po úspěšném přihlášení vygeneruje uživatelův ticket, který je společně ještě s informací o uživatelově uživatelském jméně a stagovské roli vrácen na původní URL.
  4. Formulářový přihlašovací modul umožňuje přihlášení i tzv. "přihlášení se jako anonymní uživatel". Některé aplikace umožňují přístup i zcela anonymním uživatelům, stejně jako mnohé webové služby jsou veřejně dostupné. V případě, že se uživatel tímto způsobem přihlásí, dostane cílová aplikace (viz dále) jako uživatelské jméno řetězec "anonymous" a dostane prázdný ticket a seznam rolí.
  5. Server Webových služeb vrátí ve své odpovědi klientovi zmíněnou COOKIE, čímž způsobí uložení této cookie do paměti uživatelova prohlížeče a příště je již možno uživatele přímo přesměrovat na server webových služeb - ten cookie přečte a uživatel bude ověřen.
  6. V případě, že se jednalo o HTTP BASIC, tak je navíc uživatelovo jméno a příjmení zaznamenáno v prohlížeči a dokud se neodhlásí, bude prohlížeč serveru webových služeb (a jen jemu) posílat identifikační údaje. Čili veškeré následující ověření je zde zajištěno i takto.
  7. Server webových služeb přesměruje uživatele na půdovní adresu (originalURL) - tedy na adresu Vašeho serveru. Navíc ale přidá tři GET parametry:
    • stagUserTicket - uživatelův ticket
    • stagUserName - uživatelské jméno (zvolil-li uživatel možnost "přihlášení se jako anonymní uživatel", je navrácen řetězec "anonymous")
    • stagUserRole - seznam rolí uživatele v IS/STAG oddělený čárkou (např. "ST,VY,KA", ...). Samozřejmě v případě ověřování pouze vůči IS/STAG se vrátí vždy jediná role. Obecně ale může mít uživatel rolí víc v případě použití jiného ověřování uživatelů (např. vůči ORIONU na ZČU)
  8. Vaše webová aplikace již podle předaných parametrů zjistí, že se jedná o ověřeného uživatele a díky uložené cookie či http autorizaci v prohlížeči může uživatele odkazovat na webové služby bez nutnosti dodávání dalších parametrů.

Ukázkoví klienti

V této kapitole bude pro ilustraci použití STAG Webových služeb ukázáno na příkladu dvou rozdílných jazyků, jak si napsat jednoduchého klienta.

  • Java - Jednoduchý REST client: SimpleRestClient.java.txt
  • PHP - Jednoduchý REST client: SimpleRestClient.php.txt
  • PHP - Balík s PHP klienty: phpclients.zip

    Balík obsahuje klienty, kteří zároveň i přímo NA UKÁZKU běží v rámci této aplikace:

    • SIMPLE - Jednoduchý, ukázkový klient zobrazující předměty a informace o nich. Používá XSLT transformaci XML -> XHTML.
    • Statistiky přijímaček - Klient obsahuje stejnou funkcionalitu jako původní "modré stránky" pro zobrazení statistik přijímacího řízení. Používá XSLT transformaci XML -> XHTML.
    • Informace o studijních programech - Klient obsahuje ukázkovou malou aplikaci v PHP pro vyhledání a zobrazení informací o studijních programech. Používá XSLT transformaci XML -> XHTML.

Pro Javu zde uvádím několik relevantních odkazů (WebServices, SOAP):

Pro PHP zde uvádím několik relevantních odkazů (WebServices, SOAP):

Časté parametry

Jako parametry Webových služeb se často opakují stejné parametry, jejichž název bude vždy stejný a význam taktéž. Proto, aby nemusel být popis u každé služby, uvádím zde seznam takových "hlavních" parametrů, jejich vysvětlení a v případě, že typicky nemusí být uváděny i jejich default hodnotu.

Název Default hodnota Popis
osCislo - Osobní číslo studenta.
lang cs Jazyk výsledku služby. U některých služeb je potřeba uvést jazyk, který ovlivňuje už výběr dat z databáze. Většinou postačí default hodnota.
ucitIdno - Identifikační číslo vyučujícího v rámci IS/STAG. Webovské služby jsou postaveny výhradně nad STAGem a protože jiné školy než ZČU nemají například ORION konta, nelze jako identifikátor použít ORION konto. Webovská služba "ucitele" však poskytuje i metody svázané s ORIONem (pro prostředí ZČU), pomocí nichž lze najít požadovaného užitele a převádět mezi ORION a STAG identitou.
katedra - Udává katedru či pracoviště školy.
predmet - Udává zkratku vyučovaného předmětu.
zkratka - Občas se jako zkratka předmětu objeví i tento název parametru.
rok aktuální akademický rok Akademický rok
semestr aktuální semestr Semestr
termIdno - Identifikační číslo zkouškového termínu
stprIdno - Identifikační číslo studijního programu
oborIdno - Identifikační číslo oboru
stplIdno - Identifikační číslo studijního plánu
sespIdno - Identifikační číslo segmentu
blokIdno - Identifikační číslo bloku
roakIdno - Identifikační číslo rozvrhové akce

Vyrovnávací paměť

Většina dotazů do databáze je na straně serveru webových služeb ukládána do lokální vyrovnávací paměti a příští dotazy na to samé jsou již vraceny bez interakce s databází. Je to především kvůli možnosti, kdy klienti budou služby volat "nezřízeně" a v situacích, kdy se to "by design" zcela nehodí (například pokaždé při generování www stránky, která obsahuje víceméně statická data). Tato metoda výrazně ulevuje v těchto případech databázi, daní za to je ovšem možnost občasné neaktuálnosti vracených dat (data jsou nějakou dobu vracena z vyrovnávací paměti i přesto, že se v databázi změnila).

Data jsou ve vyrovnávací paměti udržována různou dobu - v současnosti jsou dvě úrovně, které rozlišujeme:

  • Statická data - data, která jsou řekněme "neměnná", tj. během semestru se prakticky nemění (rozhodně se nemění během dne), ta jsou ve vyrovnávací paměti uložena 120 minut. Tj. mohou mít oproti databázi takto dlouhou ztrátu (tj. ještě tuto dobu budou webovské služby vracet "stará" data). Po této době se záznam ve vyrovnávací paměti zneplatní a je proveden nový dotaz na aktuální stav do databáze.
  • Dynamická data - data, která jsou řekněme "živá", jsou ve vyrovnávací paměti držena 5 minut. Je to dostatečně dlouhá doba na to, aby nebyla databáze zbytečně vytížena a naopak dostatečně krátká na to, aby se data často obnovovala.