Dokumentácia API - Základné informácie
Základné informácie
- Pre komunikáciu s API budete potrebovať vytvoriť prístup, to môžete urobiť v administrácii na Prepojenie > API.
- API je na adrese: https://NAZOV-PROJEKTU.admin.ZNACKA-SERVERU.upgates.com/api/v2.
- Každá požiadavka, ktorá má v tele JSON, by mala mať hlavičku Content-Type: application/json.
- V prípade chyby vracia API JSON s textom správy a zodpovedajúcim stavovým kódom.
- API pracuje v kódovaní UTF-8, tzn. obsah všetkých požiadaviek musí byť v tomto kódovaní.
Autentizácia
- Musíte si v administrácii založiť prístup do API.
- Autentizácia prebieha pomocou HTTP Basic authentication.
- Každá požiadavka musí mať hlavičku Authorization. Hodnotou tejto hlavičky je Basic a v base64 zakódované login:heslo.
- Celá hlavička môže vyzerať napr. takto: Authorization: Basic dGVzdDp0ZXN0
- Po 5-tich zlých pokusoch sa API zablokuje a vracia 403
Stavové kódy
- 200 OK - úspešne spracovaná požiadavka, vo väčšine prípadov vracia JSON (viď popis konkrétnych endpointov)
- 301 Moved Permanently - e-shop bol presunutý na iný server. V tomto prípade server nevracia hlavičku Location, len v tele požiadavky vracia JSON s novou adresou { "api_url": "https://NAZOV-PROJEKTU.admin.ZNACKA-SERVERU.upgates.com/api/v2" }. Je potrebné ju zmeniť na všetkých miestach, kde je použitá pôvodná adresa.
- 400 Bad Request - zlá požiadavka, nevalidné JSON v tele požiadavky, pokiaľ požiadavka vyžaduje JSON, musí to byť JSON Object
- 401 Unauthorized - chyba pri autentizácii, chýbajúca hlavička pre autentizáciu alebo zlé prihlasovacie údaje
- 403 Forbidden - API užívateľ nie je aktívny, alebo bol prekročený maximálny počet pokusov o prihlásenie, užívateľ nemá práva na endpoint alebo metódu endpointu
- 404 Not Found - zlá URL adresa požiadavky
- 405 Method Not Allowed - nepodporovaná metóda API alebo metóda konkrétneho endpointu nie je implementovaná
- 413 Payload Too Large - prekročená veľkosť PUT požiadavky - počet položiek v JSON (viď Rate Limiting)
- 429 Too Many Requests - prekročený maximálny počet požiadaviek (viď Rate Limiting)
- 500 Internal Server Error - chyba servera, pokiaľ nastane kontaktujte technickú podporu Upgates
- 501 Not Implemented - metóda nie je implementovaná
HTTP metódy
Pre prepísanie HTTP metódy môžete použiť hlavičku X-HTTP-Method-Override. Požiadavka môže byť napr. POST, ale pokiaľ bude v požiadavke táto hlavička s hodnotou DELETE, vyhodnotí sa ako DELETE. API podporuje nasledujúce HTTP metódy:
- POST - vytvorenie
- PUT - aktualizácia
- DELETE - zmazanie
- GET - získanie údajov
Dátové typy
Položky, ktoré sú v popisoch jednotlivých endpointov tučne sú povinné, dátový typ je uvedený v zátvorke pri každej položke v popise jednotlivých API.
- bool - true / false, 1 / 0
- string - štandardný reťazec znakov v UTF-8
- int - celé číslo
- float - desatinné číslo, ako oddeľovač desatinných miest používajte bodku
- array - pole hodnôt
- object - JSON Object
- email - validná e-mailová adresa
- date - dátum zapísaný ako reťazec znakov podľa ISO 8601
- language - kód jazyka podľa ISO 639-1
- currency - kód meny podľa ISO 4217
- country - kód krajiny podľa ISO 3166-1 alpha-2
Rate Limiting (Obmedzenie prevádzky)
Aby nedošlo, či už neúmyselne zlým návrhom, alebo úmyselne k príliš veľkému zahlteniu API požiadavky, je API obmedzené.
Obmedzenie prihlásenia
- Je obmedzený počet pokusov o prihlásenie, tzn., že môžete urobiť len 5 zlých prihlásení za 1 hodinu na jednu IP adresu. Potom API zablokuje prístup a vracia stav 403. Opäť sa používa Floating Time Window.
Obmedzenie veľkosti požiadavky
- Je obmedzená veľkosť PUT požiadavky, tzn. že v JSON môže byť maximálne 100 položiek. Pokiaľ je tento počet prekročený, nevykoná sa žiadna operácia (API všetky údaje zahodí) a vracia stav 413.
Súbežné požiadavky
- Na API je možné vykonávať len 3 súbežné požiadavky, pokiaľ je toto prekročené vracia sa stav 429.
Ako na API napojenie (rady a tipy)
Pre maximálnu optimalizáciu API odporúčame tieto postupy:
- väčšina endpointov má možnosť filtrovať položky podľa času poslednej zmeny, tzn. že si môžete vytiahnuť (napr. produkty) od času posledného volania API a tým ušetriť čas a množstvo požiadaviek na sťahovanie produktov
- v PUT a POST požiadavke je možné posielať až 100 položiek, tým sa zakladanie alebo aktualizácia výrazne zrýchli a nie je nutné volať API s jednou položkou
- zvážte ako často je potrebné API volať, mnohokrát sa stáva, že voláte API zbytočne často, najčastejšie GET požiadavky pre objednávky
- pre každé napojenie si vytvorte zvláštny prístup (užívateľa), ktorému obmedzíte prístup len na tie služby, ktoré potrebuje, v budúcnosti je potom jednoduchšie také napojenie deaktivovať alebo zrušiť
Testovanie
Pre testovanie API môžete použiť:
- Rozšírenie Postman pre Google Chrome.
- Rozšírenie RESTED pre Mozilla Firefox.
- Upgates API client - náš vlastný jednoduchý API klient v PHP.