Věcný obsah, základní pojmy - Web API

API rozhraní systému IS FLORES (dále jen Web API) je otevřené rozhraní nad systémem IS FLORES postavené na principech REST a webových technologiích (HTTP protokolu). Umožňuje IS FLORES propojit s jinými aplikacemi a automaticky navázat vzájemnou komunikaci. Automatizace firemních procesů výrazně šetří rutinní práci zaměstnanců a snižuje tak počet chyb.

Web API umožňuje komunikaci s jinými systémy prostřednictvím protokolu HTTP (verze 1.1) a http metod. Jedná se o RESTful rozhraní. Sestává ze dvou níže uvedených komponent, které spolu vzájemně komunikují. Pro provoz Web API je nutné mít Web API správně nakonfigurováno. Viz Nastavení Web API.

Jaké jsou další výhody?

  • Umožňuje rozložení zátěže na více serverů a přináší tak škálovatelnost a vysokou dostupnost.
  • Obsahuje výkonný dotazovací jazyk, pomocí kterého lze získat přesně ta data, která uživatel potřebuje.
  • Umožňuje komunikaci s IS FLORES z libovolného programovacího jazyka a operačního systému.
  • Implementuje standard Swagger, dnes známý jako Open API.

Co je vlastně Web API laicky, viz Co je vlastně Web API a K čemu slouží.

REST je architekturou rozhraní, která je navržená pro distribuované prostředí. Na rozdíl od známých XML-RPC nebo SOAP je REST orientován datově a nikoliv procedurálně. Stav aplikace a chování je vyjádřen takzvaným zdrojem (resource), každý zdroj musí mít unikátní identifikátor URL. REST podporuje čtyři základní metody, které jsou známé pod označením CRUD, tedy vytvoření dat (Create), získání požadovaných dat (Retrieve), změnu (Update) a smazání (Delete). Tyto metody jsou implementovány pomocí odpovídajících metod HTTP protokolu.

Požadavky kladené na architektonický styl vyhovující paradigmatu REST:

  • Oddělený klient-server - Při návrhu REST API musí být klientské a serverové aplikace na sobě zcela nezávislé. Jedinou informací, kterou by klientská aplikace měla znát, je URI požadovaného zdroje.
  • Bezestavovost - Každý požadavek musí obsahovat všechny informace nezbytné pro jeho zpracování. REST API nevyžadují žádné relace na straně serveru. Serverové aplikace nesmějí ukládat žádná data související s požadavkem klienta.
  • Ukládání do mezipaměti - Je-li to možné, měly by být prostředky kešovatelné na straně klienta nebo serveru. Odpovědi serveru také musí obsahovat informace o tom, zda je pro dodaný zdroj povoleno ukládání do mezipaměti. Cílem je zlepšit výkon na straně klienta a zároveň zvýšit škálovatelnost na straně serveru.
  • Jednotné rozhraní - Všechny požadavky API na stejný zdroj by měly vypadat stejně, bez ohledu na to, odkud požadavek pochází.
  • Vícevrstvý systém - V REST API procházejí volání a odpovědi různými vrstvami. Obecně platí, že se klientské a serverové aplikace nepřipojují přímo k sobě. V komunikační smyčce může být řada různých prostředníků. Rozhraní REST API musí být navrženo tak, aby klient ani server nebyli ovlivněni tím, zda komunikují s koncovou aplikací nebo prostředníkem.

HTTP je komunikační protokol, který se využívá pro komunikaci webového serveru s klientským softwarem. HTTP je založený na zasílání požadavků a odpovědí na ně. Klient provede HTTP požadavek (request) a webový server mu na něj odpoví pomocí HTTP odpovědí (response).

Klient posílá serveru požadavek obsahující URL zdroje a metodu, kterou o něj žádá. Nepovinnou součástí požadavku pak mohou být hlavičky a tělo.

Adresa URL rozhraní API je strukturována podobně jako „běžná“ adresa URL webových stránek, ale konvence pojmenování jsou trochu jiné a obvykle dodržují přísnější organizační logiku.

Adresa URL v API má obvykle 5 části:

  • Základní URL – je počáteční částí adresy URL rozhraní API. Skládá se z protokolu, hostu a portu. Např.: http://localhost:80
  • Jméno spojení - část URL určující nad jakým DB spojením má server požadavek provést. Např.: /develop
  • Kontroler - organizační celek, typicky název BO v množném čísle. Např.: /storecards

  • Koncový bod (endpoint) - identifikuje, ke kterému zdroji chce klient přistupovat. Např.: /{id}.

    Pokud provádíte dotaz nad konkrétním BO, potom použijte endpoint, např: /{id}/confirm, a nepředávejte id jako query parametr ani v těle dotazu.

  • Query string – skládá se z query parametrů, které slouží k doplnění API dotazu o dodatečné informace ovlivňující jeho zpracování. Např.: ?executor=outprocess

Úplná adresa URL rozhraní API spojí tyto segmenty do adresy URL:

http://localhost:80/develop/storecards/{id}?executor=outprocess

Parametry se zapisují tak, že za adresou následuje otazník a za ním zapsané páry ve formátu klíč=hodnota. Páry jsou odděleny znakem &. V případě pravdivostního parametru, pokud je uveden jako poslední parametr v query stringu, není třeba uvádět hodnotu a bere se jako by byla použita hodnota True.

Query string primárně neslouží k přenosu dat, ale metadat, nepoužívejte jej například pro předání seznamu ID, to patří do těla, neboť zde neprobíhá komprese a URl má jen omezenou délku.

Rezervované znaky mají v URL zvláštní význam a pokud mají být použity mimo jejich vyhrazený význam, musí být zakódovány.

Query string primárně neslouží k přenosu dat, ale metadat, nepoužívejte jej například pro předání seznamu ID, to patří do těla, neboť zde neprobíhá komprese a URl má jen omezenou délku.

Znak Kódování
␣ %20
! %21
" %22
# %23
$ %24
% %25
& %26
' %27
( %28
) %29
* %2A
+ %2B
, %2C
/ %2F
: %3A
: %3B
: %3D
? %3F
@ %40
[ %5B
] %5D

Web API metody a funkce v IS FLORES
Metoda Funkce
GET

Účelem metody GET je získat data zdroje ze serveru. Metoda požadavku GET je považována za bezpečnou operaci, což znamená, že by neměla změnit stav žádného zdroje na serveru. Metodu je teoreticky možné použít s tělem, ale není to zvykem a nedělejte to.

Získá pole s daty skladových karet:

GET http://localhost:80/develop/storecards

Získá data skladové karty s id 1000000101:

GET http://localhost:80/develop/storecards/1000000101
POST

Tato metoda se obvykle používá k odesílání dat ke zpracování serverem. Často se používá pro vytváření nových zdrojů nebo aktualizaci stávajících. Operace POST není považována za bezpečnou operaci, protože má pravomoc aktualizovat stav serveru a při provádění způsobit potenciální vedlejší účinky na stav serveru. Nemusí být idempotentní, což znamená, že může ponechat data a zdroje na serveru v jiném stavu při každém vyvolání.

Vytvoří novou skladovou kartu:

POST http://localhost:80/develop/storecards
PUT

Metoda PUT se používá k aktualizaci existujícího zdroje na serveru. Je definována jako idempotentní, což znamená, že více stejných požadavků PUT by mělo mít stejný účinek jako jeden požadavek. Metoda HTTP PUT je definována jako idempotentní, což znamená, že více identických požadavků HTTP PUT by mělo mít stejný účinek jako jeden požadavek. Stejně jako POST není považována za bezpečnou operaci.

Modifikuje existující skladovou kartu:

PUT http://localhost:80/develop/storecards/1000000101
DELETE

Tato metoda se používá k odstranění konkrétního zdroje ze serveru. Je idempotentní a není bezpečná.

Smaže existující skladovou kartu:

DELETE http://localhost:80/develop/storecards/1000000101

Hlavičky umožňují klientovi a serveru předávat další informace s HTTP požadavkem nebo odpovědí. Hlavička HTTP se skládá z názvu, v němž se nerozlišují malá a velká písmena, za ním následuje dvojtečka a poté samotná hodnota.

Více viz Web API - HTTP hlavičky.

Tělo požadavku slouží k odeslaní dat klientem serveru. Tělo odpovědi naopak obsahuje data, která server odesílá klientovi. Nejčastějším textovým formátem pro výměnu dat jsou JSON a XML. Binární forma se používá pro připojení obrázků, videí, zvuku a dalších netextových souborů. Formát a velikost posílaných dat jsou popsány pomocí hlaviček Content-Type and Content-Length.

Pokud v naší implementaci posíláme binární data, např obrázky jako součást JSON, kódujeme je pomocí base64.

Server posílá klientovi odpověď na požadavek obsahující stavový kód odpovědi. Nepovinnou součástí odpovědi, pak mohou být hlavičky a tělo, které jsou popsané už v části s požadavkem.

Stavové kódy jsou rozděleny do pěti kategorií. První číslice stavového kódu definuje třídu odpovědi, zatímco poslední dvě číslice nemají žádnou klasifikační nebo kategorizační roli. Standardem je definováno pět tříd:

  • 1xx informační odpověď – požadavek byl přijat, proces pokračuje

  • 2xx úspěšný – požadavek byl úspěšně přijat, pochopen a přijat

  • 3xx přesměrování – pro dokončení požadavku je třeba provést další kroky

  • 4xx chyba klienta – požadavek obsahuje špatnou syntaxi nebo jej nelze splnit

  • 5xx chyba serveru – serveru se nepodařilo splnit zjevně platný požadavek

Důležité stavové kódy a kdy je použít:

  • 200 OK - Požadavek byl úspěšný a server vrátil požadovaná data

  • 201 Created - Požadavek byl úspěšný a byl vytvořen nový zdroj

  • 204 No Content - Server úspěšně zpracoval požadavek a nevrací žádný obsah

  • 304 Not Modified - Zdroj nebyl změněn od verze určené v hlavičce požadavku If-Modified-Since nebo If-None-Match. V takovém případě není potřeba zdroj znovu přenášet, protože klient stále má dříve staženou kopii.

  • 400 Bad Request - Požadavek byl neplatný nebo nesprávný

  • 401 Unauthorized - Klient postrádá platná ověřovací pověření pro požadovaný prostředek

  • 403 Forbidden - Nastane pokud nemá uživatel práva na provedení požadavku

  • 404 Not Found - Požadovaný zdroj nebyl na serveru API nalezen, nepoužívat pokud výsledek nějakého omezení je prázdná množina, k tomu to neslouží

  • 500 Internal Server Error - Při zpracování požadavku došlo na serveru k chybě, jedná se o neočekávanou neošetřenou výjimku

Servery podporují http content-negotiation, v současnosti je nicméně ve většině případů jediným podporovaným formátem JSON, s následujícími výjimkami:

Web API umožňuje práci s daty ve formátech, které je možné bezpečně serializovat do formátu JSON - konkrétně dtInteger, dtSmallInt, dtWord, dtInt64, dtFloat, dtBCD, dtCurrency, dtBoolean, dtDate, dtDateTime, dtTime, dtString, dtMemo, dtFmtMemo, dtBlob, dtVarBytes, dtBytes, dtTypedBinary, dtGraphic a dtGuid (ne všechny datové typy jsou v systému IS FLORES skutečně používány).

Zvláštní pozornost je zapotřebí věnovat práci s datumy (a časy). V některých případech je přes Web API sice technicky možné na objektu nastavit hodnotu dtDateTime (včetně času), ale aplikace IS FLORES předpokládá, že příslušná položka časový údaj neobsahuje a při práci s takto vytvořenými nebo změněnými záznamy může v některých situacích dojít k neočekávaným výsledkům. Typickým příkladem je datum dokladu (DocDate$DATE), které by mělo obsahovat pouze datumovou část.

V případě pochybností si vyhledejte strukturu příslušného business objektu v popisu Struktur a definic F1Doc.chm. V obou případech bude u příslušné položky uveden typ dtDateTime, ale ve sloupci Popis bude uvedeno buď Datum... (např. Datum dokladu) nebo Datum a čas... (např. Datum a čas vytvoření). Pokud je v popisu uvedeno pouze Datum (nikoli Datum a čas), zapisujte do příslušné položky pouze datumovou část (bez času).

Od verze 23.1. jsou položky s hodnotou 0 v API místo ISOStringu vráceny s hodnotou null. Hodnota null je zároveň použitelná v klausuli where a vyhodnocuje se jako 0.

Web API od verze 23.1. respektuje práva k funkcím. Práva se přebírají z nastavení v agendě Role, záložka Práva k funkcím nebo Skupiny rolí podle toho, co primárně pro nastavení práv která firma využívá. Práva se přebírají podle jednotlivých metod.

Nevizuálním uživatelům Web API je tedy potřeba nastavit stejná Práva k funkcím jako k ostatním uživatelům. Případně lze dočasně využít PrivilegiaObcházet práva k API.

Web API respektuje také práva k objektům, která je potřeba nevizuálním uživatelům nastavit, případně je možné využít agendy Zpřístupnění položek pro API, kde lze nastavit výjimky.

Rozdíly proti stávajícím webovým službám (webovému API) IS FLORES:

  • Vše, co potřebujete k provozu API je k dispozici v rámci instalace IS FLORES, dostupné po nainstalování IS FLORES.

    V posledních verzích vč. podpory https protokolu (tj. není nutno předřazovat ještě nějaký externí WS jako proxy).

  • Neprogramujete (prostřednictvím skriptování) na straně IS FLORES. Tj. veškeré objekty jsou ve výchozím stavu k dispozici a manipulujete s nimi deklarativně, tj. posíláte Web API nějaký JSON na určitou URL a tím vlastně říkáte, co chcete, aby se s daným Business objektem (BO) stalo.
  • Licencování - REST API systému IS FLORES je licencováno počtem uživatelů, kteří k němu mají přístup. U webového API webových služeb se požadavky vždy zpracovávají pod jedním konkrétním uživatelem, a když je potřeba přihlásit jiného uživatele, je nutné vypnout celého klienta a znovu spustit. V REST API je možné "přepínání uživatelů za běhu", resp. autentizace je součástí každého požadavku.

Web API jako celek sestává ze dvou komponent. Fyzicky se jedná o dva soubory ve složce, ve které je nainstalován systém IS FLORES (klient).

  • Web API server - APIServer.jar ClosedViz více ... Komponenta v Javě, které klienti zasílají HTTP požadavky a od které dostávají zpátky odpovědi.

    Kromě samotné aplikace Web API serveru (APIServer.jar) je ke spuštění Web API (případně instalaci a provozu Windows služby) zapotřebí ještě obsah složky AbraWebAPI (která je rovněž součástí instalace IS FLORES). Dávkový soubor APIServer.ps1 používaný ke spouštění/instalaci/odinstalaci API serveru předpokládá, že tato složka bude v rámci adresářové struktury bezprostředně podřízená složce, ve které se nachází APIServer.jar (a APIServer.ps1). Složka AbraWebAPI obsahuje dvě podsložky:

    • jre.win - Java Runtime Environment (JRE) - prostředí nezbytné pro běh API serveru; když spustíte APIServer.ps1, z PowerShell skriptu se spustí toto prostředí, kterému je aplikace APIServer.jar předána jako parametr:

      .\AbraWebAPI\jre.win\bin\java.exe -jar .\APIServer.jar

      JRE je zapotřebí při používání Web API v režimu aplikace (zpravidla používaném v testovacím provozu) i v režimu služby (zpravidla používaném v ostrém provozu).

    • nssm - Non-Sucking Service Manager - nástroj využívaný k instalaci spustitelného souboru jako Windows služby. NSSM je na rozdíl od JRE zapotřebí pouze při provozu Web API v režimu služby.

  • API knihovna - ApiLib.dll ClosedViz více ... Komponenta implementovaná v Delphi, která řeší vlastní zpracování požadavků (business logiku).

Architektura rozhraní Web API se ve verzi IS FLORES 21.3 změnila. V minulosti bylo rozhraní realizováno trojicí Windows aplikací WebAPIServer.exe, WebAPISupervisor.exe a WebAPIWorker.exe. Nové řešení je jednodušší a díky podpoře vícevláknového zpracování požadavků také výkonnější.

Jak to vypadá, když pošlete z HTTP klienta požadavek na REST API:

Klient pošle HTTP požadavek, server požadavek obdrží a předá ho API knihovně (prostřednictvím nativního volání metody handleRequest, která je v knihovně implementována). Knihovna zařídí vyhodnocení požadavku v souladu s business logikou systému IS FLORES a vrátí odpověď serveru, který ji následně přetlumočí klientovi.

Všechny komponenty Web API rozhraní podporují podrobně nastavitelné sledování činnosti s využitím standardního logovacího subsystému.

K logování služeb Web API ("business logiky") slouží skupina AS~Group.