[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 klientatakto:

[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ícemož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, tedysysté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řenatribut 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 SQLsyntaxi, 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í dlespec. seznamu viz. další článek.

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

filter.eq[{field}] možné i takto filter[{field} - operátor rovnáse

filter.neq[{field} - operátor nerovná se

filter.in[{field} - operátor IN

filter.lt[{field} - operátor menšínež

filter.gt[{field} - operátor větší než

filter.lte[{field} - operátor menší než nebo rovno

filter.gte[{field} - operátor větší než neborovno

Řazení bude nastavitelné takto:

sort.asc={field} možné i takto sort={field} - řazeno vzestupně

sort.desc={field} - řazenosestupně

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

page.size={number} - počet položek na stránce

page.number={number} - číslostránky

page.limit={number} - limit počtu stranek

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 URLparametrů 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é akcivů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řebamapová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ázvuparametru).

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:

	...

Toto nastavení umožňuje klienta a rok zadat jak přímo v URL odkazu mezilomí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:

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é jakoběžné parametry akce, ve své původní formě:

_page_url="size=50&number=1"

Analogicky pak i _where_url a_sort_url:

_where_url="filter.eq[klient]=10023&filter.eq[rok]=2021"

_sort_url="sort.desc=mesic"

Hodnoty jsou třeba při tvorbě lepšíchchybový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:

_where - hodnoty filtrovacíchparametrů;

_where_url - URL encoded hodnoty filtrovacích parametrů;

_sort - hodnoty parametrů pro řazení

_sort_url - URL encoded hodnoty parametrůpro řazení

_page - stránkovací parametry

_page_url - URL encoded stránkovací parametry

Kromě konfigurační settings.mxl volby default-size existuje ješte default-sort. Je-litato 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 prodebug

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:

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

V response by pak mohlo být:

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 tentoje na místo atributu query v případě řazení zapsán v order.

	... 

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