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ží.

Jedním z požadavků uživatelů na desktopové ekonomické systémy je otevřené rozhraní, tj. nějaká technologie, která jej zpřístupní a umožní importovat a exportovat data, příp. další operace. Výměna dat se v praxi většinou provádí vlastním formátem postaveným na XML, CSV nebo JSON, přičemž ke komunikaci se využívají různá rozhraní:

  • COM/DCOM/Acti­veX/OLE: technologie, které jsou velmi používané na Windows platformě. Nevýhodou je jednak omezenost použití na jednu platformu (Windows) a jednak relativní složitost.
  • Pouštění z příkazové řádky: celkem originální postup, kdy připravíme XML a spustíme program, který si data naimportuje. Nevýhodou tohoto řešení je, že neumožňuje síťový přístup, anebo jen velmi omezeně.
  • WebServices: poměrně silný kandidát, který je hojně využíván napříč programovacími jazyky a platformami. Slabou stránkou tohoto rozhraní je složitost.
  • REST API: rozhraní postavené na webových technologiích (HTTP), velmi jednoduché na používání. Pro jeho prozkoumání a také vyvolání stačí uživateli běžný webový prohlížeč. Protokol HTTP umožňuje velký rozsah funkcí. Mimo jiné nabízí autorizaci, cachování, expiraci či vysokou škálovatelnost.
  • aj.

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 tabulky níže.

Web API metody a funkce v IS FLORES
Metoda Funkce
GET Spustit
POST Přidat
PUT Opravit
DELETE Vymazat

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 Privilegia Obchá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, 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, 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.