WEXBO API

ÚVOD

Táto dokumentácia poskytuje informácie o API rozhraní pre vývojárov, prostredníctvom ktorého je možné získať prístup do jednotlivých účtov (profilov) vedených v systéme WEXBO. Naše rozhranie API funguje ako webová služba REST, ktorá je založená na jednoduchej komunikácii s protokolom HTTP, pričom na výmenu dát využíva dátový formát JSON. Dokumentácia popisuje aktuálnu verziu označovanú ako v1.

Podrobné informácie o systéme WEXBO nájdete na stránkach https://wexbo.com.

Autorizácia

Každé volanie požiadavky na REST API musí byť autorizované. Vo všetkých volaniach tak musí byť prítomná HTTP hlavička Authorization obsahujúca API token, ktorý reprezentuje prístup ku konkrétnemu účtu.

Authorization: Bearer {API_TOKEN}požiadavkahttp

API token získate po prihlásení sa do administrácie vášho účtu cez https://admin.wexbo.com v sekcii DOPLNKY / PLUGINY v plugine s názvom API.

Návratový stavový kód HTTP pre volanie, pri ktorých nebol používateľ prihlásený, je 401 Unauthorized.

Požiadavka

HTTP metódy

Podporované sú bežné metódy protokolu HTTP, ktoré sa zvyčajne používajú medzi webovými službami REST. Každá metóda protokolu HTTP má inú funkciu, pričom spôsob výkladu je popísaný v nasledujúcom zozname:

HTTP hlavičky

Požiadavka na volanie musí obsahovať HTTP hlavičku autorizácie s tokenom a HTTP hlavičku s verziou API. Aktuálna verzia API je v1.

Authorization: Bearer {API_TOKEN}
Content-Type: application/vnd.wexbo.v1+json; charset=utf-8požiadavkahttp

URL adresa

Základná URL adresa pre požiadavky API je pre všetky profily rovnaká, a to:

https://api.wexbo.com/

Celková požiadavka sa skladá z HTTP hlavičiek, konkrétnej metódy, endpointu, parametrov popísaných nižšie, prípadne aj tela požiadavky vo formáte JSON.

https://api.wexbo.com/{ENDPOINT}/{NULL|ID|COUNT}?{URL_PARAMETERS}požiadavkaget

Koncový bod

Zároveň URL adresa musí obsahovať aj tzv. endpoint (koncový bod). Konečná URL adresa pre volanie požiadavky pre zobrazenie zoznamu produktov bude vyzerať nasledovne:

https://api.wexbo.com/productspožiadavkaget

Zozname všetkých dostupných endpointov nájdete nižšie v dokumentácii v sekcii REFERENCE, kde sú detailne popísané, keďže každý endpoint má vlastné parametre, dostupné metódy a rôznu štruktúru pre dáta požiadavky či samotné dáta odpovede.

Identifikátor

V prípade použitia metódy GET pre zobrazenie konkrétneho detailu jedného záznamu, je nutné hneď za endpointom pridať {ID} (identifikátor záznamu). Napr. pre zobrazenie produktu s ID 1000001 je to URL adresa požiadavky:

https://api.wexbo.com/products/1000001požiadavkaget

URL parametre

Do URL požiadavky je možné pridať niektoré všeobecné nepovinné URL parametre, ktorých zoznam nájdete v tabuľke nižšie. Bližšie informácie niektorých všeobecných URL parametrov sú popísané nižšie v dokumentácii.

https://api.wexbo.com/products?fields=id&limit=25&page=1&offset=0&include=pagination,links&sort=id&direction=descpožiadavkaget

Polia

Každý endpoint obsahuje predvolené polia, ktoré sú súčasťou JSON tela odpovede na požiadavku už zahrnuté v parametri data. V prípade zadania ďalších hodnôt do URL parametra fields je možné v odpovedi v parametri data zobraziť ďalšie polia, ktoré konkrétny endpoint podporuje. Príklad zadania požiadavky pre zobrazenie ďalších polí:

https://api.wexbo.com/products?fields=id,code,namepožiadavkaget

{
···
"data": [
{
"id": 1000001,
"code": "product_code",
"name": "Product name",
},
···
],
···
}odpoveďjson

Všetky podporované polia pre URL parameter fields sú popísané v konkrétnom endpointe.

Doplnkové parametre

V odpovedi je možné zobraziť aj ďalšie doplnkové parametre a to prostredníctvom URL parametra include. Do parametra je možné zadať viacero hodnôt oddelených čiarkou, napr.:

https://api.wexbo.com/products?include=pagination,linkspožiadavkaget

Odpoveď

Súčasťou každej odpovede servera na požiadavku klienta je telo vo formáte JSON s parametrami result, data, errors.

Stav

Úspešne spracovaná požiadavka obsahuje v JSON tele odpovedi, hneď na začiatku parameter result s hodnotou ok. Naopak chybne spracovaná požiadavka obsahuje parameter result s hodnotou error.

{
"result": "ok",
···
}odpoveďjson

Dáta

Základom odpovede na požiadavku sú samotné dáta, ktoré sú obsiahnuté v JSON tele odpovedi v parametri data. V prípade požiadavky s metódou DELETE (zmazanie záznamu) má daný parameter prázdnu hodnotu. V opačnom prípade parameter obsahuje predvolené polia, prípadne aj polia zahrnuté v URL parametry fields.

{
···
"data": {
"id": 1,
···
},
···
}odpoveďjson

Stránkovanie

V prípade požiadavky na zoznam záznamov (metóda GET bez ID) sa zobrazuje len určitý počet záznamov, pričom sa využíva tzv. stránkovanie. Predvolene je počet zobrazujúcich záznamov na stranu nastavený na hodnotu 25.

Nastaviť je možné aj inú hodnotu a to prostredníctvom URL parametra limit, do ktorého je možné zadať hodnotu od 1 do 250. Aktuálne nastavené stránkovanie požiadavky sa vždy zobrazí v odpovedi stránkovania v parametri paging.

https://api.wexbo.com/products?limit=50požiadavkaget

Predvolene sa zobrazí prvá stránka so zoznamom položiek, keďže URL parameter page má predvolenú hodnotu 1. Pridaním daného parametra do URL adresy požiadavky je možné zobraziť zoznam položiek ďalších stránok.

https://api.wexbo.com/products?page=2požiadavkaget

Namiesto parametra page je možné použiť URL parameter offset, kedy sa majú zobraziť záznamy od nastavenej hodnoty. Predvolene má daný parameter hodnotu 0 (od začiatku). Ak je zadaný súčasne aj parameter page, tak parameter offset sa v požiadavke neuplatní, teda pre stránkovanie je možné použiť len jeden z nich. Nastaviť je možné napr. zobrazenie záznamov od 50-teho záznamu 25 záznamov na stranu, teda záznamy v poradí 50 až 75:

https://api.wexbo.com/products?limit=25&offset=50požiadavkaget

Súčasťou odpovede takýchto požiadaviek je HTTP hlavička X-Pagination-Metadata obsahujúca informácie o stránkovaní.

X-Pagination-Metadata: {pages:10,page:1,offset:0,count:25,total:250,paging:25}odpoveďhttp

Ak chcete informácie o stránkovaní zobraziť priamo v JSON tele odpovede, je nutné v požiadavke využiť parameter include obsahujúcu hodnotu pagination.

https://api.wexbo.com/products?include=paginationpožiadavkaget

{
···
"pagination": {
"pages": 10,
"page": 1,
"offset": 0,
"count": 25,
"total": 250,
"paging": 25,
"status": "continue"
},
···
}odpoveďjson

Odkazy

Odpoveď obsahuje aj HTTP hlavičku Link obsahujúcu automaticky generované odkazy pre jednoduchšiu možnosť vykonania ďalšej akcie. V prípade stránkovania sú to napríklad odkazy na požiadavky pre zobrazenie ďalšej strany záznamov.

Link: <https://api.wexbo.com/products?page=2&include=links>; rel="self", <https://api.wexbo.com/products?page=1&include=links>; rel="first", <https://api.wexbo.com/products?page=1&include=links>; rel="prev", <https://api.wexbo.com/products?page=3&include=links>; rel="next", <https://api.wexbo.com/products?page=9&include=links>; rel="last"odpoveďhttp

Ak chcete informácie o odkazoch zobraziť priamo v JSON tele odpovede, je nutné v požiadavke využiť parameter include obsahujúcu hodnotu links.

https://api.wexbo.com/products?page=2&include=linkspožiadavkaget

{
···
"links": {
"self": "https://api.wexbo.com/products?page=2&include=links",
"first": "https://api.wexbo.com/products?page=1&include=links",
"prev": "https://api.wexbo.com/products?page=1&include=links",
"next": "https://api.wexbo.com/products?page=3&include=links",
"last": "https://api.wexbo.com/products?page=9&include=links"
},
···
}odpoveďjson

Chyby

Zoznam konkrétnych informácií týkajúcich sa chýb požiadavky nájdete vždy v JSON tele odpovede na konci v parametri errors. V prípade úspešného spracovania položky by mal byť zoznam parametra prázdny (prázdne array pole). Napriek tomu sa v danom zozname môžu nachádzať aj varovania s kódom 100, ktoré nie sú závažnými chybami, teda nebránia spracovaniu požiadavky, ale len upozorňujú na prípadné nezrovnalosti v požiadavke.

{
···
"errors": [
{
"code": 404,
"msg": "Information about error",
"error": "...",
"field": "..."
},
{
"code": 100,
"msg": "Just some warning",
"error": "...",
"field": "..."
}
]
}odpoveďjson

Kódy odpovedí

Súčasťou každej odpovede servera na požiadavku klienta je kód o stave odpovedi v hlavičke (HTTP response status codes). Väčšina odpovedí zvyčajne obsahuje nižšie uvedené kódy odpovedí.

Úspešné spracovanie

Chyba pri spracovaní

Denník zmien

ODKAZY