FlexiBee API - URL parametry

Stránkování

Téměř každý uživatel FlexiBee API bude dřív nebo později potřebovat nějakým způsobem stránkovat výsledky, které mu FlexiBee vrací. Například jen z toho důvodu, že bez jiného určení FlexiBee vrací jen prvních 20 výsledků. Implicitně je totiž stránka velká 20 záznamů.
Pokud je tedy potřeba z FlexiBee získat další stránky nebo mít stránku větší je nutné začít používat parametry.

Důležité parametry jsou:
limit
Tento parametr určuje kolik záznamů bude na jedné stránce.
Pokud potřebujeme získat stránku se všemi záznamy najednou tak je nutné tento parametr nastavit na hodnotu 0.
demo.flexibee.eu/c/demo/adresar.xmlvrátí se prvních dvacet záznamů z evidence adresář.

demo.flexibee.eu/c/demo/adresar.xml?limit=5vrátí se prvních pět záznamů z evidence adresář.

demo.flexibee.eu/c/demo/adresar.xml?limit=0vrátí se všechny záznamy z evidence adresář.

start
Pokud je tedy požadováno stránkování výsledků tak jen limit nestačí. Je nutné použít i parametr start, který řekne na kolikátém záznamu stránka začíná.
První záznam a zároveň výchozí hodnota je start=0.
demo.flexibee.eu/c/demo/adresar.xml?limit=5&start=0vrátí stránku o velikosti 5 záznamů z evidence adresář a začne na prvním záznamu.

demo.flexibee.eu/c/demo/adresar.xml?limit=5&start=5vrátí druhou stránku o velikosti 5 záznamů z evidence adresář. Druhá stránka je určena parametrem start s hodnotou 5.

add-row-count
Pokud stránkujeme záznamy je dobré vědět kdy máme skončit. Je tedy také možné do URL přidat parametr, který do výstupu doplní celkový počet záznamů, přes které je možné stránkovat. Tento parametr se jmenuje add-row-count a nabývá hodnot true nebo fale podle toho zda se má celkový počet doplňovat nebo ne.
demo.flexibee.eu/c/demo/adresar.xml?limit=5&add-row-count=truevrátí stránku o velikosti 5 záznamů z evidence adresář. V elementu winstrom je doplně atribut rowCount, který obsahuje celkový počet záznamů.

demo.flexibee.eu/c/demo/adresar.json?limit=5&add-row-count=truestejný postup je možné aplikovat i na JSON výstup. Pak bude do výstupu doplněno "@rowCount":"457".

Pro co nejrychlejší odezvu FlexiBee doporučuji používat stránkování!
Další optimalizací může být odstranění parametru add-row-count při načítání dalších stránek. Není totiž nutné se při každé stránce dotazovat zda se tento počet nezměnil. Navíc získání tohoto čísla je ve FlexiBee další dotaz do databáze a každý zbytečný dotaz navíc je zdržení.

Úrovně detailu

Dalším velmi důležitým parametrem je detail. Tento parametr umožňuje ovlivňování jaké vlastnosti jednotlivých záznamů dané evidence se budou ve výstupu nacházet.
Je to ale velmi rozsáhlá tématika, takže ji rozeberu v samostatném článku.
Dokumentace k jednotlivým detailům je dostupná na stránkách FlexiBee.

Řazení

Ve většině případů je potřeba záznamy, které FlexiBee vrací mít rovnou i seřazené podle nějaké vlastnosti. Proč bychom si měli záznamy řadit ve své aplikaci když i toto za nás může vyřešit FlexiBee.
Řazení záznamů se provádí parametrem order. Hodnota tohoto parametru je pak vlastnost, podle které chceme řadit.
demo.flexibee.eu/c/demo/adresar.xml?order=kodPokud tedy do URL doplníme parametr order=kod, FlexiBee nám bude vracet záznamy seřazené podle vlastnosti Zkratka. Záznamy budou seřazeny vzestupně.

demo.flexibee.eu/c/demo/adresar.xml?order=kod@DPokud potřebujeme mít záznamy seřazeny sestupně (výhodné například pro řazení podle částek, faktury s nejvyšší hodnotou budou na začátku), tak ještě za název vlastnosti doplníme @D

Řazení podle více hodnot se provádí opakovaným použitím parametru order. Pak záleží i na pořadí jak jsou do URL parametry order vkládány.
demo.flexibee.eu/c/demo/adresar.xml?order=stat&order=kodTento příklad vrátí záznamy z evidence adresář seřazené nejdříve podle státu a pokud je stát stejný tak budou záznamy řazeny podle zkratky.

demo.flexibee.eu/c/demo/adresar.xml?order=kod&order=statDotaz s řazením nejdříve podle zkratky a pak podle státu samozřejmě vrátí jiné výsledky.

Parametr order je možné použít i přímo ve webovém rozhraní FlexiBee.

Ostatní

FlexiBee umožňuje v URL ještě další spoustu parametrů.
Kompletní seznam se nachází na stránce www.flexibee.eu/api/dokumentace/ref/urls/, takže já zmíním jen ty nejdůležitější a nejpoužívanější.

only-ext-ids
Výstupy z FlexiBee vypisují u každého objektu identifikátory.
pokud se použije tento parametr budou vypisovány jen externí identifikátory objektů.
demo.flexibee.eu/c/demo/adresar.xml?only-ext-ids=true
demo.flexibee.eu/c/demo/adresar.json?only-ext-ids=trueV tomto případě tedy zmizely vnitřní identifikátory FlexiBee a ve výstupu jsou jen externí identifikátory u záznamů, které je obsahují.

no-ext-ids
Opakem předchozího parametru je parametr no-ext-ids. Pokud je použit tento parametr nebudou ve výstupu žádné externí identifikátory. Parametr no-ext-ids slouží především ke zrychlení načítání dat z FlexiBee. Každý pokus o načtení externích identifikátorů výpis zpomaluje.
demo.flexibee.eu/c/demo/adresar.xml?no-ext-ids=true
demo.flexibee.eu/c/demo/adresar.json?no-ext-ids=true
no-ids
Obdoba předchozího parametru ale ve výstupu nebudou žádné vnitřní identifikátory FlexiBee. Takže mohou zůstat zobrazeny například externí identifikátory.
demo.flexibee.eu/c/demo/adresar.xml?no-ids=true
demo.flexibee.eu/c/demo/adresar.json?no-ids=true
code-as-id
Tímto parametrem se místo interních identifikátorů FlexiBee vypíše u evidencí, které to podporují, zkratka jako identifikátor.
demo.flexibee.eu/c/demo/adresar.xml?code-as-id=true
demo.flexibee.eu/c/demo/adresar.json?code-as-id=true
Tímto parametrem je možné v kombinaci s no-ids zajistit přenosy dat mezi jednotlivými firmami ve FlexiBee. Například, pokud bude potřeba přenést adresář z firmy A do firmy B, je nejlepší způsob použít export přes REST API z firmy A a import do firmy B. URL pro získání adresáře bude vypadat například takto takto:
demo.flexibee.eu/c/demo/adresar.xml?code-as-id=true&no-ids=true