Dokumentace Web API

Web API systému ABRA Flores 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í.

Seznam dostupných OpenAPI definic systému ABRA Flores 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.

Pro některé návazné scénáře je k dispozici i specializovaný dokumentační endpoint /api-docs/dynsqls, který vrací za jednotlivé agendy seznam všech dostupných datových zdrojů DynSQL, včetně označení výchozího zdroje. Tento endpoint lze využít například při dohledávání tiskových sestav a exportů navázaných na konkrétní agendu.

Kompletní dokumentaci lze pak získat takto:

GET {server-api}:{port}/{spojeni}/api-docs/openapi

V OpenAPI dokumentaci naleznete:

  • definice všech BO a zdrojů
  • zdokumentované metody, které je možno na zdrojích použít
  • aj.

Oproti dřívější dokumentaci je nyní možné dokumentaci získat nejen jako jeden velký JSON, ale i distribuovaně ve více dílčích JSONech. Rozdělení do více souborů je realizováno dvěma způsoby:

  1. dle typu části openapi - paths, schemas...
  2. dle endpointu/kontroleru - typicky tedy za všechny cesty, které patří ke zvolenému BO

Např. dílčí dokumentaci za endpoint firmy pak získáme zavoláním:

GET {server-api}:{port}/{spojeni}/api-docs/openapi/firms

Ve výchozím stavu je OpenAPI vraceno v distribuované formě, tzn. všechny jeho části jsou v samostatných souborech, které je možné získat dotazem na příslušný endpoint. Pokud je potřeba vrátit OpenAPI v jednom souboru, je to možné vynutit použitím query parametru distrib=false. OpenAPI 3.0 je v obou režimech kompatibilní s nástroji Swagger UI, případně Swagger Editor, které doporučujeme pro uživatelské prohlížení dokumentace. V nich je však nutné z výkonových důvodů procházet dokumentaci vždy pouze za vybraný kontroler.

Původní dokumentační endpointy založené na technologii Swagger (OpenAPI 2.0) jsou označeny jako zastaralé a od verze 27.1 budou odstraněny. Jedná se o endpointy /swagger, /path a /path/{detail}. Pro dokumentaci API proto používejte endpointy ve formátu OpenAPI 3.0 dostupné na cestách pod /openapi.

Pro základní přehled dostupné dokumentace a pro vizuální zobrazení je možné použít také HTML rozhraní:

GET {server-api}:{port}/{spojeni}/api-docs/overview

Zobrazí se vizuální dokumentační aplikace s přehledem dostupných částí API dokumentace, včetně OpenAPI kontrolerů, modelů, serverstate objektů a importních manažerů.

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.

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ů readonly a writeonly určujících přístupová práva k dané položce,
  • vlastních rozšíření specifických pro systém ABRA Flores (např. x-abra-field-enumeration nebo atributu fkProtectedByViewPurchasePrices v x-abra-field-attributes).

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=true je 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 jako paths, schemas a 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í.

Příklad vyvolání dokumentace v online nástroji Swagger Editor ke kontroleru /firms.

Kromě dokumentace business objektů poskytuje API také statické popisy Stav na serveru. Popisují pomocí OpenAPI speciální objekty dostupné pouze ve stavu na serveru

Pro získání seznamu všech speciálních objektů a jejich popisů slouží endpoint:

GET {server-api}:{port}/{spojeni}/api-docs/serverstateobject

Pro získání detailního popisu konkrétního objektu slouží hodnota Detail:

GET {server-api}:{port}/{spojeni}/api-docs/serverstateobject/{detail}

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>

Seznam i detailní popis importních manažerů lze zobrazit také ve vizuální dokumentační aplikaci na stránce /api-docs/overview, v sekci Importní manažery. Seznam lze filtrovat a po výběru importního manažera se zobrazí jeho parametry.

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.

Seznam dostupných modelů je k dispozici na endpointu:

GET {server-api}:{port}/{spojeni}/api-docs

Zobrazení pomocí modelů není ve formátu OPenAPI, ale ve formátu JSON.

Strukturu dat v daném modelu pak získáme přes:

GET {server-api}:{port}/{spojeni}/api-docs/model/<hodnota>

Popis vybraných položek:

Položka Popis
x-abra-bo-class-name Pokud je tato položka vyplněná, jedná o objektový kontroler. Pokud není, jedná se o funkcionální kontroler.
x-abra-field-enumeration

V této položce jsou uvedeny informace o možných hodnotách výčtových polí. Obsahuje subpoložky x-value (hodnota) a x-caption (popis), které reprezentují možné hodnoty, jež položka může nabývat. 

"x-abra-field-enumeration": [
    {
        "x-caption": "Hlavní činnost",
        "x-value": 0
    },
    {
        "x-caption": "Vedlejší činnost",
        "x-value": 1
    }
]
 
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í.