WEXBO API

INSTRUCTION

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.

Authorization

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}requesthttp

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.

Request

HTTP methods

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 headers

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-8requesthttp

URL address

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}requestget

Endpoint

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/productsrequestget

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.

Identifier

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/1000001requestget

URL parameters

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=descrequestget

Fields

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,namerequestget

{
···
"data": [
{
"id": 1000001,
"code": "product_code",
"name": "Product name",
},
···
],
···
}responsejson

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

Additional parameters

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,linksrequestget

Response

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

Status

Ú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",
···
}responsejson

Data

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,
···
},
···
}responsejson

Pagination

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=50requestget

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=2requestget

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=50requestget

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}responsehttp

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=paginationrequestget

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

Links

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"responsehttp

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=linksrequestget

{
···
"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"
},
···
}responsejson

Errors

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": "..."
}
]
}responsejson

Response codes

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í.

Successful processing

Error in processing

Changelog

REFERENCES