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.