Dokumentace API - Základní informace

Základní informace

• Pro komuninaci s API budete potřebovat vytvořit přístup, to můžete udělat v administraci na Propojení > API.
• API je na adrese: https://NAZEV-PROJEKTU.admin.ZNACKA-SERVERU.upgates.com/api/v2.
• Každý požadavek, který má v těle JSON, by měl mít hlavičku Content-Type: application/json.
• V případě chyby vrací API JSON s textem zprávy a odpovídající stavový kód.
• API pracuje v kódování UTF-8, tzn. obsah všech požadavků musí být v tomto kódování.

Autentizace

• Musíte si v administraci založit přístup do API.
• Autentizace probíhá pomocí HTTP Basic authentication.
• Každý požadavek musí mít hlavičku Authorization. Hodnotou této hlavičky je Basic a v base64 zakodované login:heslo.
• Celá hlavička může vypadat např. takto: Authorization: Basic dGVzdDp0ZXN0
• Po 5-ti špatných pokusech se API zablokuje a vrací 403

Stavové kódy

• 200 OK - úspěšně zpracovaný požadavek, ve většině případů vrací JSON (viz. popis konkrétních endpointů)
• 301 Moved Permanently - e-shop byl přesunut na jiný server. V tomto případě server nevrací hlavičku Location, pouze v těle požadavku vrací JSON s novou adresou { "api_url": "https://NAZEV-PROJEKTU.admin.ZNACKA-SERVERU.upgates.com/api/v2" }. Je potřeba ji změnit na všech místech, kde je použita původní adresa.
• 400 Bad Request - špatný požadavek, nevalidní JSON v těle požadavku, pokud požadavek vyžaduje JSON, musí to být JSON Object
• 401 Unauthorized - chyba při autentizaci, chybějící hlavička pro autentizaci nebo špatné přihlašovací údaje
• 403 Forbidden - API uživatel není aktivní, nebo byl překročen maximální počet pokusů o přihlášení, uživatel nemá práva na endpoint nebo metodu endpointu
• 404 Not Found - špatná URL adresa požadavku
• 405 Method Not Allowed - nepodporovaná metoda API nebo metoda konkrétního endpointu není implementována
• 413 Payload Too Large - překročena velikost PUT požadavku - počet položek v JSONu (viz. Rate Limiting)
• 429 Too Many Requests - překročen maximální počet požadavků (viz. Rate Limiting)
• 500 Internal Server Error - chyba serveru, pokud nastane kontaktujte technickou podporu Upgates
• 501 Not Implemented - metoda není implementována

HTTP metody

Pro přepsání HTTP metody můžete použít hlavičku X-HTTP-Method-Override. Požadavek může být např. POST, ale v pokud bude v požadavku tato hlavička s hodnotou DELETE, vyhodnotí se jako DELETE. API podporuje následující HTTP metody:

• POST - vytvoření
• PUT - aktualizace
• DELETE - smazání
• GET - získání dat

Datové typy

Položky které jsou v popisech jednotlivých endpointů tučně jsou povinné, datový typ je uveden v závorce u každé položky v popisu jednotlivých API.

• bool - true / false, 1 / 0
• string - standardní řetězec znaků v UTF-8
• int - celé číslo
• float - desetinné číslo, jako oddělovač desetinných míst používejte tečku
• array - pole hodnot
• object - JSON Object
• email - validní emailová adresa
• date - datum zapsané jako řeťezec znaků dle ISO 8601
• language - kód jazyka dle ISO 639-1
• currency - kód měny dle ISO 4217
• country - kód země dle ISO 3166-1 alpha-2

Rate Limiting (Omezení provozu)

Aby nedošlo, ať už neúmyslně špatným návrhem, nebo úmyslně k přílišnému zahlcení API požadavky, je API omezeno.

Omezení přihlášení

• Je omezen počet pokusů o přihlášení, tzn, že můžete udělat pouze 5 špatných přihlášení za 1 hodinu na jednu IP adresu. Potom API zablokuje přístup a vrací stav 403. Opět se používá Floating Time Window.

Omezení velikosti požadavku

• Je omezena velikost PUT požadavku, tzn. že v JSONu může být maximálně 100 položek. Pokud je tento počet překročen, neprovede žádná operace (API veškerá data zahodí) a vrací stav 413.

Souběžné požadavky

• Na API je možno provádět pouze 3 souběžné požadavky, pokud je toto překročeno vrací stav 429.

Jak na API napojení (rady a tipy)

Pro maximální optimalizaci API doporučujeme tyto postupy:

• většina endpointů má možnost filtrovat položky podle času poslední změny, tzn. že si můžete vytáhnout (např. produkty) od času posledního volání API a tím ušetřit čas a množství požadavků na stahování produktů
• v PUT a POST požadavku je možné posílat až 100 položek, tím se zakladání nebo aktualizace výrazně zrychlí a není nutné volat API s jednou položkou
• zvažte jak často je třeba API volat, mnohokrát se stává že voláte API zbytečně často, nejčastěji GET požadavek pro objednávky
• pro každé napojení si vytvořte zvláštní přístup (uživatele), kterému omezíte přístup pouze na ty služby které potřebuje, v budoucnu je pak jednodušší takové napojení deaktivovat nebo zrušit

Testování

Pro testování API můžete použít:

• Rozšíření Postman pro Google Chrome.
• Rozšíření RESTED pro Mozilla Firefox.
• Upgates API client - náš vlastní jednoduchý API klient v PHP.