Dokumentace Web API
Web API systému ABRA Gen je navrženo a dokumentováno pomocí standardu OpenAPI 3.0. OpenAPI je otevřená specifikace pro popis RESTful API, která umožňuje srozumitelně definovat jednotlivé endpointy, parametry, datové struktury, způsoby autentizace a další aspekty API. V této kapitole naleznete informace o způsobech jejího zobrazení.
Hlavní rozcestník dokumentace Web API systému ABRA Gen je k dispozici zde:
GET {server-api}:{port}/{spojeni}/api-docs/openapis
Vrácená data z endpointu /api-docs/openapis obsahují kromě identifikátoru kontroleru (CLSID) také identifikátor třídy business objektu (BOCLSID), pokud se jedná o objektový kontroler. To umožňuje jednoduše navázat na další struktury či metadata business objektů definovaných v systému.
Kompletnú dokumentáciu je potom možné získať takto:
GET {server-api}:{port}/{spojeni}/api-docs/openapi
V OpenAPI dokumentácii nájdete:
- definícia všetkých BO a zdrojov
- zdokumentované metódy, ktoré je možné na zdrojoch použiť
- a. i.
Oproti predošlej dokumentácie je teraz možné dokumentáciu získať nielen ako jeden veľký JSON, ale i distribuovane vo viacerých čiastkových JSONoch. Rozdelenie do viacerých súborov je realizované dvoma spôsobmi
- podľa typu časti openapi - paths, schemas...
- podľa endpointu/kontrolera - typicky teda za všetky cesty, ktoré patria k zvolenému BO
Napr. čiastkovú dokumentáciu za endpoint firmy potom získame zavolaním:
GET {server-api}:{port}/{spojeni}/api-docs/openapi/firms
Defaultne je openapi vrátené v distribuovanej forme, tzn. všetky jeho časti sú v samostatných súboroch, ktoré je možné získať dopytom na príslušný endpoint. Pokiaľ je chcené, aby bolo openapi vrátené v jednom súbore je to možné vynútiť použitím query parametra distrib=false. Openapi 3 je v oboch režimoch kompatibilné s nástrojmi Swagger UI, prípadne Swagger Editor, ktoré odporúčame pre používateľské prehliadanie dokumentácie. V nich je však nutné z výkonostných dôvodov prechádzať dokumentáciu vždy len za vybraný kontroler.
Pro základní přehled dostupných kontrolerů a pro vizuální zobrazení dokumentace je možné použít také HTML rozhraní. Pokud klient požaduje výstup ve formátu text/html, lze využít následující endpointy:
GET {server-api}:{port}/{spojeni}/api-docs/openapis
Zobrazí se jednoduchá webová stránka s přehledem dostupných controllerů ve formě tabulky. Po kliknutí na konkrétní controller se otevře detailní dokumentace.
GET {server-api}:{port}/{spojeni}/api-docs/openapi/{controller}
Zobrazí se stránka s dokumentací vybraného controlleru pomocí nástroje SwaggerUI.
GET {server-api}:{port}/{spojeni}/api-docs/openapi
Zobrazí se stránka s celkovou dokumentací všech controllerů v jednom zobrazení pomocí SwaggerUI. Tento výstup může být velmi rozsáhlý a při zobrazení v prohlížeči může dojít k přetížení paměti.
Pro tato zobrazení jsou použity dvě jednoduché HTML stránky:
apidoc.html– stránka s přehledem všech dostupných controllerů a tabulkou.apidocdetail.html– stránka s vizualizací dokumentace vybraného controlleru pomocí SwaggerUI.
OpenAPI dokumentace definuje schémata pro jednotlivé business objekty (BO) a jejich vlastnosti včetně podpory:
- odkazů na jiné business objekty (referencí),
- kolekcí (seznamů objektů nebo hodnot),
- atributů
readonlyawriteonlyurčujících přístupová práva k dané položce, - vlastních rozšíření specifických pro systém ABRA Gen (např.
x-abra-field-enumeration).
Dotazování na OpenAPI dokumentaci podporuje parametr distrib, který ovlivňuje způsob vrácení dat:
- Při
distrib=false(výchozí) je dokumentace vrácena jako jeden soubor. -
Při
distrib=trueje dokumentace vrácena ve formátu, který obsahuje pouze základní metadata a odkazy na jednotlivé části specifikace OpenAPI pomocí$ref. Jedná se o tzv. distribuovanou formu, kde jsou části jakopaths,schemasa další zpřístupněny odděleněTato struktura umožňuje načítání dokumentace po jednotlivých segmentech a je vhodná zejména pro interaktivní nástroje jako Swagger UI nebo Swagger Editor, které si mohou jednotlivé části dotáhnout dynamicky podle potřeby.
U jednotlivých endpointů může být uveden atribut deprecated, který signalizuje plánované odstranění nebo změnu. Atribut zároveň obsahuje informaci o verzi, ve které ke změně dojde.
Zobrazení dokumentace pomocí integrovaného SwaggerUI zohledňuje všechny výše uvedené vlastnosti a umožňuje jejich interaktivní prozkoumání.
Kromě dokumentace business objektů poskytuje API také statické popisy pro importní manažery (IM). Tyto popisy obsahují seznam všech parametrů IM, jejich typy a další příznaky, přičemž struktura popisu je stejná jako u business objektů.
Pro získání seznamu všech zaregistrovaných importních manažerů a jejich popisů slouží endpoint:
GET {server-api}:{port}/{spojeni}/api-docs/importmanager
Pro získání detailního popisu konkrétního importního manažera použijte jeho název v URL:
GET {server-api}:{port}/{spojeni}/api-docs/importmanager/<nazev_importniho_managera>
Příklad dotazu na konkrétní IM (import objednávky přijaté do dodacího listu):
GET http://localhost:80/demodata/api-docs/importmanager/receivedordertobillofdelivery
Kromě tohoto statického popisu je možné s importními manažery pracovat také stavově (vytvořit instanci, měnit parametry a spustit) prostřednictvím endpointu /serverstate.
Zoznam dostupných modelov je k dispozícii na endpointe:
GET {server-api}:{port}/{spojeni}/api-docs
Zobrazenie pomocou modelov nie je vo formáte OPenAPI, ale vo formáte JSON.
Štruktúru dát v danom modeli potom získame prostredníctvom:
GET {server-api}:{port}/{spojeni}/api-docs/model/<hodnota>
Popis vybraných položiek:
GET http://localhost:81/demodata/api-docs/model/absence
Skriptovací systém byl rozšířen o podporu automatické dokumentace API funkcí, kterou lze volat přímo z API. Dokumentace je registrována přímo v balíčcích skriptů společně s implementací API funkcí.
Více informací včetně příkladu najdete na stránce Příklady pokročilého skriptování.