API – seznamy, filtrování a stránkování

Některé API metody vrací seznam položek (např. příchody, objednávky, pohyby na provizním účtu).
Tyto metody mají společné chování – stejné vstupní parametry pro filtrování a stránkování a také jednotnou strukturu výstupu.

Tahle stránka ti vysvětlí, jak číst odpověď, jak filtrovat a jak stránkovat.

Výstupní data

Odpověď metod, které vrací seznam, obsahuje vždy tyto položky:

results – pole objektů s jednotlivými položkami seznamu
page – číslo aktuální stránky
count – počet vrácených položek v odpovědi
filteredCount – počet položek odpovídajících aktuálním filtrům
totalCount – celkový počet položek bez filtrů

Příklad odpovědi

Konkrétní položky v results zde nejsou uvedeny:

{
  "results": [
    ...
  ],
  "page": 1,
  "count": 10,
  "filteredCount": 18,
  "totalCount": 624,
  "requestId": "..."
}

Co to znamená v praxi:
Celkem existuje 624 položek (např. objednávek),
z toho 18 odpovídá aktuálním filtrům a vráceno bylo prvních
10 položek (stránka 1, velikost stránky 10).

Filtrování

Do požadavku můžeš přidat jeden nebo více filtrů. Filtry se předávají jako GET parametry a podle nich se vyberou položky, které API vrátí.

Základní filtry

ID – vrátí pouze položku s konkrétním ID záznamu
lastID – vrátí pouze položky, jejichž ID je vyšší než zadaná hodnota (vhodné pro načítání nových položek)

Tip

lastID je ideální, pokud pravidelně dotahuješ nové položky
od posledního známého ID a nechceš řešit stránkování dozadu.

Příklad – objednávky s ID vyšším než 1234

https://api.wedos.as/partner/orders?lastID=1234

Stránkování

Seznamy lze stránkovat, tedy vracet jen po určitých dávkách. API umožňuje vrátit maximálně 1000 položek na jedno volání.

Výchozí hodnoty

page – výchozí 1
count – výchozí 100
count – max 1000

K čemu je to dobré

Když chceš jen malý náhled (např. 10 položek), dáš count=10.
Když stahuješ větší dávky, drž se rozumně (třeba 100-300), ať zbytečně nezatěžuješ endpoint.

Příklad – 10 položek na druhé stránce

Vrátí položky 11 až 20:

https://api.wedos.as/partner/orders?page=2&count=10

Když si nebudeš jistý

Pokud si nebudeš jistý filtrováním nebo stránkováním v konkrétní metodě, můžeš využít veřejné diskuzní fórum, případně nám napiš přímo na e-mail:
affiliate@wedos.com.