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ť:

Na tejto stránke

Další zdroje informací

Facebook poradna

Výměna zkušeností, rady a tipy mezi provozovateli e-shopů na systému UPgates.

Přejít do poradny

Akademie

Získejte znalosti od našich specialistů na marketing, obchod, právo a podnikání.

Přejít do akademie

Novinky z Blogu

Co nového jsme pro vás připravili nebo chystáme najdete na blogu.

Přejít do blogu

Nepodařilo se Vám najít tu správnou odpověď?

Kontaktujte naši technickou podporu, která je tu pro vás od pondělí do pátku 8:00 až 16:00 hod.

Zákaznická podpora