Realizace RESTful Web API rozhraní v systému ABRA

Webové služby tak, ako sú k dispozícii v systéme ABRA Gen (tzn. ABRA WS server a agenda webových služieb a operácií) je možné využiť ešte ďalším spôsobom a to na riešenie komunikácie medzi systémom ABRA Gen, Apacheom a klientom (web. prehliadačom), resp. obsluhou požiadaviek priamo prostredníctvom HTTP protokolu a jeho metódy GET, PUT, POST,.... Jedná se v podstatě o realizace RESTful Web API rozhraní v systému ABRA.

Na toto riešenie sa dodáva ABRA modul mod_abra_wsserver_http_2_2.so. Modul neobsluhuje webové služby, ale obsluhuje priamo požiadavky HTTP protokolu (GET, PUT, POST, HEAD...), umožňuje získať zo servera akékoľvek dáta a umožňuje dáta pomocou tohto modulu tiež nahrávať do systému ABRA. Volanie prebieha pomocou HTTP požiadavky, napr. zadaním adresy do prehliadača, napr. http://nasServer/http/httpservice/calendar/kaha (čo znamenajú jednotlivé časti URL adresy, viď podrobnejšie ďalej Spôsob volania).

Stručný princíp (podrobnosti viď ďalej): Modul sa namapuje na nejaké URL, napr. /http (ako, viď ďalej). v systéme ABRA Gen musí existovať v agende Webové služby zadaná služba s určitým menom a s presne špecifikovaným rozhraním a parametrami (URL rozhrania) a k nej musí existovať v skriptovaní balíček skriptov s metódami (GET, PUT, ...) a s presne špecifikovaným správaním, čo sa má stať, keď príde ako URL adresa (resp. jej časť) to a to. Ktokoľvek sa teda môže obrátiť na http adresu (prostredníctvom webového prehliadača), modul na Apachi z jej začiatku rozpozná, že ide o úlohu pre neho, zoberie zvyšnú časť adresy (bez tej časti URL, na ktorú je on sám namapovaný), spojí sa s ABRA WS serverom a odovzdá cez neho príslušnú časť URL cesty ako string (reťazec) do skriptovania ABRA Gen. Príslušný skript ju "rozpársuje" (rozloží na časti) a podľa toho vykoná požadované úkony. (Napr. nájde požadovanú faktúru, "vytlačí" ju do súboru vo formáte pdf a ako pdf ju vráti naspäť webovému serveru, prípadne klientovi, ktorý o ňu žiadal (tzn. vo webovom prehliadači sa zobrazí náhľad pdf požadovanej faktúry, alebo sa vykoná dopyt do aktivít a vráti sa kalendár vo formáte *.icalc a pod.).

Nejde o klasické webové služby, pretože tie využívajú na komunikáciu XML a SOAP protokol, viď Webové služby v systéme ABRA - všeobecne,, kým tu sa obsluhuje priamo metóda GET, PUT,... a dáta sa posielajú priamo v požadovanej podobe. Do modulu webových služieb v systéme ABRA Gen bola táto možnosť zakomponovaná preto, že z technických dôvodov (aby odozva bola dostatočne rýchla atď.) využíva rovnaký mechanizmus ako protokol SOAP (tzn. využíva ABRA WS server a jeho systém obsluhy požiadaviek pomocou kernelov, zásuvný modul do Apache a platí pre ňu rovnaký systém jeho konfigurácie ako pre ABRA WSDL moduly.).

Schéma využitia RESTful rozhrania v systéme ABRA. Porovnajte so schémou HTTP komunikácie (bez ABRA http modulu) uvedeným v rámci výkladu pojmu HTTP protokol

Popis a inštalácia modulu mod_abra_wsserver_http_2_2.so:

Modul mod_abra_wsserver_http_2_2.so je realizovaný na rovnakom princípe ako sú ABRA WSDL moduly a rovnakým spôsobom sa aj inštaluje a konfiguruje. Tzn. ide o plugin webového servera Apache. Tento plugin sa spojí s ABRA WS serverom. Adresa a port servera, s ktorým sa má modul spojiť, sa nachádzajú v textovej podobe v súbore abrawsserver.conf v podadresári conf (teda tak, ako je bežné v rámci iných modulov Apache). Ak tento súbor neexistuje, modul si vytvorí nový a uloží do neho východiskové nastavenie (localhost:3121). Formát nastavenia uloženého v tomto súbore je AdresaIP (alebo meno servera):Port. Port nie je povinný, pokiaľ nie je zadaný, použije sa východiskový port 3121.

Dodávaný modul mod_abra_wsserver_http_2_2.so sa nakopíruje do adresára, kde má Apache moduly rovnako ako je to v prípade ABRA WSDL modulov, viď vyššie a podobne sa upraví konfiguračný súbor Apache httpd.conf, tzn. ktorý sa nachádza v podadresári \conf. Tu je potrebné zabezpečiť nahranie nášho modulu. Za miesto, kde sa pridávajú jednotlivé moduly (LoadModule), umiestní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 akej ceste sa budeme na daný modul odkazovať. (Je to obdoba toho, čo sa v rámci ABRA WSDL modulov väčšinou zadáva ako "/AWS".) Tzn. zjednodušene povedané "namapujeme" modul na nejakú URL adresu resp. jej časť, konkrétne daný modul sa bude volať na adrese http://menoservera.sk/HTTP. (V predchádzajúcej URL adrese je menoservera.sk identifikácia servera, kde je Apache nainštalovaný.)

Implementácia v systéme ABRA Gen

K dispozícii sú dva základné modely. Voľba modelu sa riadi parametrom HTTPInterfaceVersion v konfiguračnom súbore abraws.conf pre HTTP modul servera Apache. Tento parameter označuje číslo verzie protokolu (1=pôvodná verzia, 2=nová verzia). Súčasťou inštalácie (<inštalačný adresár systému ABRA>\Doc\webservices) je šablóna vo forme tmpl súborov abraws.conf.tmpl s popisom parametrov a určená pre ľahké vytvorenie potrebného konfiguračného súboru.

Model s piatimi VAR parametrami

V agende Webové služby musí byť definovaná webová služba ľubovoľného mena a v agende Webové operácie musia byť nadefinované operácie rovnakého mena, ako je http požiadavka. Teda napr. GET, PUT, POST,... Tieto operácie musia mať pevne stanovený počet a typ parametrov, ktoré je možné automaticky predvyplniť pomocou funkcie Parametre pre obsluhu vyvolania HTTP protokolu:

• Path: String - Časť URL adresy po odstránení názvu servera, namapovania http modulu a názvu služby, napr. /calendar/kaha
• Header: String (VAR) - Výstupná hlavička http požiadavky. Je tu možné zadať parametre, ktoré sa pridajú do hlavičky odpovede na požiadavku (okrem štandardných). Syntax je NAZOVPARAMETRA=HODNOTA+CRFL (jednotlivé parametre sa oddeľujú CRLF).
• Content: String (VAR) - Samotný obsah požiadavky. Sem sa vyplní obsah požiadavky pre odpoveď.
• ContentType: String (VAR) - Typ obsahu (text/html, text/XML, application/pdf .... ).
• ContentEncoding: String (VAR) - Kódovanie obsahu (UTF-8 atď.).
• Argument:String (VAR)

V agende Balíčky skriptov musí byť skript typu Knižnica obsahujúci príslušné skripty pre metódy GET, PUT, .... Implementácia procedúry v skriptovaní musí obsahovať ako prvý parameter Self typu TNxWebServicesHelper (rovnako ako parameter Self v príapde Webových služieb) a potom musia nasledovať vyššie spomenuté parametre. Hlavičku skriptu je možné vygenerovať pomocou funkcie Štandardná hlavička v agende Operácie.

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 spôsob, kedy sa do skriptu okrem parametra SELF odovzdajú len 2 parametre Request a Response, ktoré volanie značne zjednodušujú a ponúkajú mnoho ďalších možností, ktoré je možné využiť. Podrobný popis jednotlivých polí, ktoré je možné parametrom Request a Response odovzdať, je uvedený napr. na anglickej wikipédii. Na vygenerovanie základnej hlavičky skriptu je možné v agende Operácie využiť funkciu Hlavička pre obsluhu HTTP ver. 2.

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

Spôsob volania:

URL adresa potom bude zadaná v tvare http://menoservera.sk/aaa/MenoSluzbyVSystemeABRA, kde

* http://menoservera je identifikácia servera, kde beží Apache, 
* aaa je namapovanie ABRA hhtp modulu na určitú cestu v konfigurácii Apache,
* MenoSluzbyVSystemeABRA je názov služby v agende Webové služby.

Toto je povinná časť URL adresy. Za lomkou môže nasledovať čokoľvek ďalšie, napr. /pdf, /icalc, /calendar/kaha a pod. Ide o ľubovoľnú cestu, ktorú skript dostane v parametri PATH.

Čo daná služba urobí, závisí od toho, čo je pre danú metódu napísané v skriptovaní pre danú časť z URL adresy. URL adresa môže být zadaná napr. http://menoservera.sk/http/MenoSluzbyVSystemeABRA/kal.ics alebo napr. http://menoservera.sk/http/MenoSluzbyVSystemeABRA/pdf s tým, že v skripte pre metódu GET je uvedené, že ak je cesta (parameter Path, viď vyššie) "kal.ics", tak sa majú z agendy Aktivity pre daného užívateľa vyhrať záznamy za aktuálny mesiac a tieto dáta sa vo formáte ics vrátia späť serveru Apache a ak je cesta "pdf", má sa stať niečo iné.

Využitie v praxi:

1. Príkladom môže byť synchronizácia kalendára Outlook/Thunderbird pomocou "icalc".

   Majme firmu so systémom ABRA Gen zaoberajúcu sa napr. upratovacími službami. Existuje tu požiadavka, aby externým pracovníkom na vzdialených pracoviskách zadával majster údaje podľa toho, koľko kto a kde v daný deň odpracuje, či má nejakú neprítomnosť a pod. , pričom túto evidenciu nezadáva priamo do systému ABRA Gen, ale prostredníctvom externej aplikácie, ktorá sa so systémom ABRA Gen spojí a zabezpečí naplnenie zadanými údajmi. Ďalej sa chce, aby každý z externých pracovníkov mal možnosť sa na svoju zadanú dochádzku pozrieť a prehliadať si ju (ale nie priamo vstupom do systému ABRA Gen (k nemu nemá prístup), ale napr. pomocou kalendára v aplikácii MS Outlook, Thunderbird a pod). Do vyhľadávača potom stačí napísať presne danú url adresu (napr. www.httpservice/kal.icc) a následne si už len prehliadať zaktualizovaný kalendár.

2. Iným príkladom je napr. možnosť zasielania informačných e-mailov odberateľom obsahujúcich odkaz napr. na číslo objednávky vo forme jednoduchého hyperlinku, ktorý si odberateľ môže "rozkliknúť" a informovať sa rýchlo a pohodlne na stav svojej objednávky.
3. A pod.

Čo je potrebné na prevádzku:

Je to podobne ako pre samotné webové služby, viď Čo je teda potrebné na prevádzku webových služieb v systéme ABRA Gen. Tu je akurát navyše bezpodmienečne nutné, aby sa operácie webovych služieb nazývali GET, PUT, POST atď. Ďalej je potrebné, aby všetky operácie mali správny počet, názvy a príznaky parametrov.

Výhody a nevýhody:

Výhodou tohto riešenia (na rozdiel od webových služieb so SOAP protokolom) je, že je jednoduché a nenáročné a dajú sa pomocou neho realizovať aj úlohy, ktoré pomocou web. služieb so SOAP protokolom realizovať nie je možné. Nevýhodou je, že obe komunikujúce strany sa musia presne dohodnúť na tom, akým spôsobom budú toto rozhrania implementovať (na rozdiel od webových služieb, kde autorovi web. služby "stačí" zverejniť ju a druhá strana ju môže použiť a to bez toho, aby sa obe komunikujúce strany museli stretnúť a komunikovať o tom, čo a ako.).