REST API

REST obecně má mít charakter orientovaný na data, nikoli na procedury. Ve flexideo tento přístup úplně třeba není, protože pomocí HTTP protokolu a XML požadavkům je možné s daty pracovat i v jiných klientech. Celý XML protokol flexideo je defakto API orientované na data. Cílem tedy není toto nahradit. Cílem je nabídnout jednodušší API pro provozované akce.

Vstupem akce může být i jiný než SOAP formát, tj. nejen libovolné XML bez přiřazení k SOAP, ale i jiné datové obsahy, zejm. pak formát JSON.

REST umožňuje i jiné HTTP metody, než-li je POST využívaný pro SOAP (GET, POST, PUT, DELETE) - popis všech formátů na vstupu a výstupu akcí Formáty akcí.

V implementaci REST API jde zejména o GET rozšíření, je nabízeno rozhraní pro přístup a také filtraci či řazení dat bez nutnosti zasílání HTTP/POST content. Akce je možné spouštět přes SOAP klíčový prostor flexideo v této syntaxi:

Návrh REST API vychází z následujících možností:

Je ke zvážení, zda neumožnit i alternativu původního SOAP volání takto:

První odlišností tedy je verzování. V kmenovém uzlu settings.mxl existuje atribut version. Slouží pro identifikaci verze dané akce, jejího buildu. REST API zavádí nový atribut api, který pokud atribut není uveden, je to chápáno jako akce verze 1.0 a pokud je uveden bude obsahovat dvě číslice oddělené tečkou. Aktuální úprava REST API je identifikována atributem api="2.0".

Zavedení verzování otevírá prostor pro budoucí standardy API (Graph QL apod).

Další odlišností je možnost parametrizace přímo v URL GETové části, kdy je žádoucí, aby bylo možné přímo do URL odkazu vložit odkaz na zdroj.

Například tak můžeme chtít pracovat pouze s daty určitého klienta, jehož ID bude definováno jako param1. Pokud tak klient bude mít ID 10023, mohla by akce pro získání základních dat klienta být volána tímto odkazem:

[web:]/api/2.0/client_detail/10023

Případně detail klienta za rok 2021, bude-li mít akce definovány 2 parametry:

[web:]/api/2.0/client_detail/10023/2021[web:]/api/2.0/client_detail?filter.eq[klient]=10023&filter.eq[rok]=2021[web:]/api/2.0/client_detail?filter.eq[klient]=10023&filter.gteq[rok]=2019

Obdobně tak by mohlo být doplněno řazení nebo stránkování (2. strana dat):

[web:]/api/2.0/client_detail?filter.eq[klient]=10023&filter.eq[rok]=2021&sort.desc=mesic&page.number=2

Kombinace dotazů jako URL parametrů za otazníkem by byla možná pouze s metodou GET, která nebude mít žádný content a také pro příp. metodu DELETE (pouze filtrace).

Metody POST a PUT pro insert a update by filtraci mít nemohly, ale mohly by mít parametry za lomítky. Bude tak možné zapsat data jednoho klienta takto:

[web:]/api/2.0/client_detail/10023
(POST) {"jmeno":"...",...}

Zachování SOAP slouží zejména pro interní protokol volání akcí. Standardní systém volání flexideo akcí nabízí totiž více možností a pro interní stavbu akcí je výhodnější. Zavedné REST API slouží pro snadnější integrace a rozšíření možností napojení na okolní systémy.

Parametry volání a jejich pozice

Parametry jsou i v rámci předávány stejně jako dosud, tedy systémem klíč+hodnota. Filtry, řazení a příp. stránkování pro GET (u metody DELETE jen filtrování), by byly předávány na vstup akce jako parsované části SQL dotazu.

V kmenovém uzlu action-steps v souboru settingu akce je pro REST API tvořen atribut params se středniky oddělenými názvy parametrů v pořadí, v jakém jsou zadatelné v URL volání služby. Není možné zadat např. pouze druhý nebo třetí parametr, pokud nebude zadán první. To ale souhlasí s logikou jejich obsahu. Navíc velmi často parametry nejsou buď vůbec nebo je nutný pouze jeden a je třeba znát jeho význam.

Specifikace URL parametrů

Úplný výčet URL parametrizace pro filtrování, řazení a stránkování. Parametrizace je chápána jako podklad pro převod na SQL syntaxi, jež bude předána jako řetězecový parametr.

URL parametrizace bude vždy chápána jako nepovinná, ale do akce bude třeba předávat jak původní znění, tak také SQL parsování verzi. V níže uvedené syntaxi je {field} nahrazováno pomocí mapování dle spec. seznamu viz. další článek.

Filtrování používá tyto možnosti:

Řazení bude nastavitelné takto:

Stránkování nabízí tyto možnosti:

Stránkování si je v implementaci realizované již na úrovni dotazu na data do databáze. Obdržená parametrizace na pozici za lomítky, tedy odkazy na zdroj jsou přiřazeny k částem dotazů, které jsou serveru poskytnuty pro dynamickou syntézu dotazu a přípravě výchozí množiny dat.

Mapování field entit na SQL výrazy

Pro účely sestavování částí SQL dotazů sloužících k filtrování, řazení a příp. i stránkování dle URL parametrů je v souboru settings.mxl zaveden nový uzel query-parts.

Nový uzel query-parts je uveden pouze v případě, že je URL mapování v dané akci vůbec možné. Dokud není uveden, akce tuto schopnost nemá (i když má api/2.0). Vyskytuje se jako první potomek kmenového uzlu action-steps.

Pro tvorbu částí dotazu pro účely filtrace, řazení a stránkování dle URL parametrů je třeba mapování SQL políček nebo jejich složených výrazů na použité názvy. Do nastavení settings.mxl v takových případech přibude uzel query-parts + uzel part (name, query, type = s/n)

Pro účely akce je třeba předávat v parametrech nejen parsovaný SQL výsledek, ale také jeho původní formu. Je zajištěna jedinečnost jmen (2 podtržítka na začátku názvu parametru).

Rozšíření struktury settings.mxl oproti interním a dalším none REST akcím - tučně vyznačené je možné rozšíření pro příklad s klientem:

<action-steps ...="" params="klient;rok">
<query-parts>
<part name="klient" query="kl.id" type="n"/>
<part name="rok" query="vykz.rok" type="n"/>
<query-parts>
<action-step ...="">
	...
</action steps>

Toto nastavení umožňuje klienta a rok zadat jak přímo v URL odkazu mezi lomítky, tak také jako URL parametr filtrování, protože v settingu je uveden jak params, tak také uzel query-parts.

Příklad parametrů v nastaveních akce:

<query-parts>
<part query="T100000.dlsud_rdncsl" name="rodneCislo" type="s"/>
<part order="E10000028" name="E10000028" type="s"/>
<part order="Erodnecislo" name="Erodnecislo" type="s"/>
</query-parts>

Dostupnost URL parametrů v akci

Původní, nijak neparsované obsahy URL parametrů, těch filtrovacích, řadících i těch za otazníkem jsou dostupné jako běžné parametry akce, ve své původní formě:

Analogicky pak i _where_url a _sort_url:

Hodnoty jsou třeba při tvorbě lepších chybových hlášek a doplňujících odkazů uvnitř odpovědí, budou-li požadovány v rámci rest metadat v body odpovědi.

Úplný výčet všech dostupných hodnot:

Kromě konfigurační settings.mxl volby default-size existuje ješte default-sort. Je-li tato volba nastavena a zároveň není v URL parametrech žádná volba třídění, je doplněna a zaslána tato výchozí. Volba default-sort může být užitečná zejména při stránkování, kdy pokud není v dotazu ORDER BY nelze používat stránkovací volby.

Parsovací požadavek pro debug

Pro účely debug je k dispozici serverový parser URL požadavků jako spec. požadavek, který umožňuje využití parsovací schopnosti serveru např. takto:

<parse-api-request api="2.0"
url-params="filter.eq[klient]=10023&filter.eq[rok]=2021&sort.desc=mesic"/>

V response by pak mohlo být:

<parse-api-request api="2.0">
<query sql="ml.id=10023 and vykz.rok=2021" url="filter.eq[klient]=10023&filter.eq[rok]=2021"/>
<sort sql="vykz.mesic desc" url="sort.desc=mesic" />
</parse-api-request>

Pokud nebude uveden page.number, bude se ten limit prosazovat formou TOP klauzule. Bude na šabloně akce, aby tuto skutečnost rozpoznala. Neuvedený size bude řešen převzetím hodnoty z nastavení v settings.mxl (např. default-size) a teprve až pak, nebyl-li by ani zde limit stanoven, dosazením obecné hodnoty.

Atribut order - part pro řazení neobsahuje odkaz do db tabulky, ale na alias sloupce. Takže tento je na místo atributu query v případě řazení zapsán v order.

<action-steps ...="" params="klient;rok">
<query-parts>
<part name="klient" query="kl.id" order="idKlienta" type="n"/>
<part name="rok" query="vykz.rok" type="n"/>
<query-parts>
<action-step ...="">
	... 
</action steps>

Nový atribut order se může používat samostatně nebo v kombinaci s atributem query ve stejném uzlu.

---

Skladba ověřovacího dotazuUmístění popisu službyREST API

---