Dokumentace API - Základní informace

Základní informace

• Pro komuninaci s API budete potřebovat login a heslo, které najdete 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

Stavové kódy

• 200 - úspěšně zpracovaný požadavek
• 400 - špatný požadavek, nevalidní JSON v těle požadavku, pokud požadavek vyžaduje JSON, musí to být JSON Object
• 401 - chyba při autentizaci (špatný login nebo heslo, špatná metoda autentizace, chybějící hlavička pro autentizaci)
• 404 - špatná URL adresa požadavku
• 405 - nepodporovaná metoda API
• 413 - překročena velikost PUT požadavku (počet položek v JSONu), viz. Rate Limiting
• 429 - překročen maximální počet požadavků, viz. Rate Limiting
• 500 - chyba serveru, pokud nastane kontaktujte technickou podporu Upgates

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

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í se budou ještě upravovat, o úpravách budeme informovat.

Na API je možno provádět pouze 3 souběžné požadavky, pokud je toto překročeno vrací HTTP 429 (viz. stavové kódy) Další omezení je při PUT požadavku na 100 položek pro aktualizaci, při překročení vrací HTTP 413 (viz. stavové kódy).

Datové typy

Položky které jsou v popisech 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

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.