Realizace RESTful Web API rozhraní v systému ABRA

Webových služeb tak, jak jsou k dispozici v systému ABRA Gen (tj. ABRA WS serveru a agendy webových služeb a operací) lze využít ještě dalším způsobem a to k řešení komunikace mezi systémem ABRA Gen, Apachem a klientem (web. prohlížečem), resp. obsluhou požadavků přímo přes HTTP protokol a jeho metody GET, PUT, POST,.... Jedná se v podstatě o realizace RESTful Web API rozhraní v systému ABRA.

Pro toto řešení je dodáván ABRA modul mod_abra_wsserver_http_2_2.so. Modul neobsluhuje webové služby, ale obsluhuje přímo požadavky HTTP protokolu (GET, PUT, POST, HEAD...), umožňuje získat ze serveru jakákoliv data a umožňuje data pomocí tohoto modulu i nahrávat do systému ABRA. Volání probíhá pomocí HTTP požadavku např. zadáním adresy do prohlížeče, např. http://nasServer/http/httpservice/calendar/kaha (co znamenají jednotlivé části URL adresy, viz podrobněji dále Způsob volání).

Stručný princip (podrobněji viz dále): Modul se namapuje na nějaké URL, např. /http (jak, viz dále). v systému ABRA Gen musí existovat v agendě Webové služby zadaná služba určitého jména a s přesně specifikovaným rozhraním a parametry (URL rozhraní) a k ní musí existovat ve skriptování balíček skriptů s metodami (GET, PUT, ...) a s přesně specifikovaným chováním, co se má stát, když přijde jako URL adresa (resp. její část) to a to. Tedy kdokoli se může obrátit na http adresu (přes webový prohlížeč), modul na Apachi z jejího počátku pozná, že se jedná o úlohu pro něj, vezme zbylou část adresy (bez té části URL, na kterou je on sám namapován), spojí se s ABRA WS serverem a přes něj předá příslušnou část URL cesty jako string (řetězec) do skriptování ABRA Gen. Příslušný skript ji "rozpársuje" (rozloží na části) a podle toho provede požadované úkony. (Např. dohledá požadovanou fakturu, "vytiskne" ji do souboru ve formátu pdf a jako pdf ji vrátí zpět webovému serveru potažmo klientovi, který ji žádal (tj. ve webovém prohlížeči se zobrazí náhled pdf požadované faktury, nebo provede dotaz do aktivit a vrátí kalendář ve formátu *.icalc apod.).

Nejde o klasické webové služby, jelikož ty využívají ke komunikaci XML a SOAP protokol, viz Webové služby v systému ABRA - obecně, kdežto zde se obsluhuje přímo metoda GET, PUT,... a data se posílají přímo v požadované podobě. Do modulu webových služeb v systému ABRA Gen byla tato možnost zakomponována proto, že z technických důvodů (aby odezva byla dostatečně rychlá atd.) využívá stejného mechanismu jako protokol SOAP (tj. využívá ABRA WS server a jeho systém obsluhy požadavků pomocí kernelů, zásuvný modul do Apache a platí pro ni stejný systém jeho konfigurace jako u ABRA WSDL modulů.).

Schéma využití RESTful rozhraní v systému ABRA. Srovnejte se schématem HTTP komunikace (bez ABRA http modulu) uvedeným u výkladu pojmu HTTP protokol

Popis a instalace modulu mod_abra_wsserver_http_2_2.so:

Modul mod_abra_wsserver_http_2_2.so je realizován na stejném principu jako jsou ABRA WSDL moduly a stejným způsobem se i instaluje a konfiguruje. Tj. jedná se o plugin webového serveru Apache. Tento plugin se spojí s ABRA WS serverem. Adresa a port serveru, se kterým se má modul spojit, se nacházejí v textové podobě v souboru abrawsserver.conf v podadresáři conf (tedy tak, jak je běžné u jiných modulů Apache). Pokud tento soubor neexistuje, modul si vytvoří nový a uloží do něj výchozí nastavení (localhost:3121). Formát nastavení uloženého v tomto souboru je AdresaIP (nebo jméno serveru):Port. Port není povinný, pokud není zadán, je použit výchozí port 3121.

Dodávaný modul mod_abra_wsserver_http_2_2.so se nakopíruje do adresáře, kde má Apache moduly stejně jako je tomu u ABRA WSDL modulů, viz výše a obdobně se upraví konfigurační soubor Apache httpd.conf, tj. který se nachází v podadresáři \conf. Tady je třeba zajistit nahrání našeho modulu. Za místo, kde se přidávají jednotlivé moduly (LoadModule), umístíme text:

LoadModule abra_wsserver_http_2_2_module modules/mod_abra_wsserver_http_2_2.so
<Location /HTTP>
SetHandler mod_abra_wsserver_http_2_2-handler
</Location>

<Location /HTTP> určuje, na jaké cestě se budeme na daný modul odkazovat. (Je obdoba toho, co je u ABRA WSDL modulů většinou zadáváno jako "/AWS".) Tj. zjednodušeně řečeno "namapujeme" modul na nějakou URL adresu resp. její část, konkrétně daný modul bude volán na adrese http://jmenoserveru.cz/HTTP. (V předchozí URL adrese je jmenoserveru.cz identifikace serveru, kde je Apache nainstalován.)

Implementace v systému ABRA Gen

K dispozici jsou dva základní modely. Volba modelu se řídí parametrem HTTPInterfaceVersion v konfiguračním souboru abraws.conf pro HTTP modul serveru Apache. Tento parametr označuje číslo verze protokolu (1=původní verze, 2=nová verze). Součástí instalace (<instalační adresář systému ABRA>\Doc\webservices) je šablona ve formě tmpl souborů abraws.conf.tmpl s popisem parametrů a určená pro snadné vytvoření potřebného konfiguračního souboru.

Model s pěti VAR parametry

V agendě Webové služby musí být definována webová služba libovolného jména a v agendě Webové operace musí být nadefinovány operace téhož jména, jako je http požadavek. Tedy např. GET, PUT, POST,... Tyto operace musí mít pevně stanovený počet a typ parametrů, které lze automaticky předvyplnit pomocí funkce Parametry pro obsluhu volání HTTP protokolu:

  • Path: String - Část URL adresy po odstranění názvu serveru, namapování http modulu a názvu služby, např. /calendar/kaha
  • Header: String (VAR) - Výstupní hlavička http požadavku. Zde lze zadat parametry, které se přidají do hlavičky odpovědi na požadavek (kromě standardních). Syntaxe je NAZEVPARAMETRU=HODNOTA+CRFL (jednotlivé parametry se oddělují CRLF).
  • Content: String (VAR) - Samotný obsah požadavku. Sem se vyplní obsah požadavku pro odpověď.
  • ContentType: String (VAR) - Typ obsahu (text/html, text/XML, application/pdf .... ).
  • ContentEncoding: String (VAR) - Kódování obsahu (UTF-8 atd.).
  • Argument:String (VAR)

V agendě Balíčky skriptů musí být skript typu Knihovna obsahující příslušné skripty pro metody GET, PUT, .... Implementace procedury ve skriptování musí obsahovat jako první parametr Self typu TNxWebServicesHelper (stejně jako parametr Self u Webových služeb) a pak musí následovat výše zmíněné parametry. Hlavičku skriptu lze vygenerovat pomocí funkce Standardní hlavička v agendě Operace.

procedure GET(Self: TNxWebServicesHelper; Path: String; var Header: String; var Content: String; var ContentType: String; var ContentEncoding: String; Arguments: String);

Model request/response

Toto je způsob, kdy se do skriptu kromě parametru SELF předají jen 2 parametry Request a Response, které volání značně zjednodušují a nabízejí mnoho dalších možností, které lze využít. Podrobný popis jednotlivých polí, která lze parametrům Request a Response předat, je uveden např. na anglické wikipedii. K vygenerování základní hlavičky skriptu lze v agendě Operace využít funkci Hlavička pro obsluhu HTTP ver. 2.

procedure test(Self: TNxWebServicesHelper; ARequest: TNxHTTPRequest; AResponse: TNxHTTPResponse);

Způsob volání:

URL adresa pak bude zadána ve tvaru http://jmenoserveru.cz/aaa/JmenoSluzbyVSystemuABRA, kde

* http://jmenoserveru je identifikace serveru, kde běží Apache,
* aaa je namapování ABRA hhtp modulu na určitou cestu v konfiguraci Apache,
* JmenoSluzbyVSystemuABRA je název služby v agendě Webové služby.

Toto je povinná část URL adresy. Za lomítkem může následovat cokoli dalšího, např. /pdf, /icalc, /calendar/kaha apod. Jedná se o libovolnou cestu, kterou skript obdrží v parametru PATH.

Objasníme na příkladu: Mějme modul mod_abra_wsserver_http_2_2.so namapovaný v serveru Apache na adresu /aaa. Dále mějme v agendě Webové služby zadanou službu pod jménem "httpservice". URL adresa pak bude http://jmenoserveru.cz/aaa/httpservice.

Co daná služba udělá, závisí na tom, co je napsáno pro danou metodu ve skriptování pro danou část z URL adresy. URL adresa může být zadána např. http://jmenoserveru.cz/http/JmenoSluzbyVSystemuABRA/kal.ics nebo např. http://jmenoserveru.cz/http/JmenoSluzbyVSystemuABRA/pdf s tím, že ve skriptu pro metodu GET je uvedeno, že je-li cesta (parametr Path, viz výše) "kal.ics", pak se mají z agendy Aktivity pro daného uživatele vyhrát záznamy za aktuální měsíc a tato data se ve formátu ics vrátí zpět serveru Apache a je-li cesta "pdf", pak se má stát něco jiného.

Využití v praxi:

  1. Příkladem může být synchronizace kalendáře Outlook/Thunderbird přes "icalc".

    Mějme firmu se systémem ABRA Gen zabývající se např. úklidovými službami. Zde existuje požadavek, aby externím pracovníkům na vzdálených pracovištích zadával mistr údaje podle toho, kolik kdo a kde v daný den odpracuje, zda má nějakou nepřítomnost apod. , přičemž tuto evidenci nezadává přímo do systému ABRA Gen, ale přes externí aplikaci, která se se systémem ABRA Gen spojí a zajistí naplnění zadanými údaji. Dále se chce, aby každý z externích pracovníků měl možnost se na svou zadanou docházku podívat a prohlížet si ji (ale nikoli přímo vstupem do systému ABRA Gen (k němu nemá přístup), ale např. přes kalendář v aplikaci MS Outlook, Thunderbird apod). Pak stačí do vyhledávače napsat přesně danou url adresu (např. www.httpservice/kal.icc) a poté si jen prohlížet zaktualizovaný kalendář.

  2. Jiným příkladem je např. možnost zasílání informačních e-mailů odběratelům obsahujících odkaz např. na číslo objednávky ve formě jednoduchého hyperlinku, který si odběratel může "rozkliknout" a informovat se rychle a pohodlně na stav své objednávky.
  3. Apod.

Co je třeba k provozu:

Obdobně jako pro samotné webové služby, viz Co je tedy třeba k provozu webových služeb v systému ABRA Gen. Zde je pouze navíc bezpodmínečně nutné, aby se operace webovych služeb jmenovaly GET, PUT, POST atd. Dále je třeba, aby všechny operace měly správný počet, názvy a příznaky parametrů.

Výhody a nevýhody:

Výhodou tohoto řešení (na rozdíl od webových služeb se SOAP protokolem) je, že je jednoduché a nenáročné a lze s ním realizovat i úlohy, které pomocí web. služeb se SOAP protokolem realizovat nelze. Nevýhodou je, že obě komunikující strany se musí přesně dohodnout na tom, jakým způsobem budou toto rozhraní implementovat (na rozdíl od webových služeb, kde autorovi web. služby "stačí" ji zveřejnit a druhá strana ji může použít, aniž by se obě komunikující strany musely potkat a komunikovat o tom, jak.).