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 jeBasic
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čkuLocation
, 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 Object401
Unauthorized - chyba při autentizaci, chybějící hlavička pro autentizaci nebo špatné přihlašovací údaje403
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 endpointu404
Not Found - špatná URL adresa požadavku405
Method Not Allowed - nepodporovaná metoda API nebo metoda konkrétního endpointu není implementována413
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 Upgates501
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
- aktualizaceDELETE
- 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 / 0string
- standardní řetězec znaků v UTF-8int
- celé číslofloat
- desetinné číslo, jako oddělovač desetinných míst používejte tečkuarray
- pole hodnotobject
- JSON Objectemail
- validní emailová adresadate
- datum zapsané jako řeťezec znaků dle ISO 8601language
- kód jazyka dle ISO 639-1currency
- kód měny dle ISO 4217country
- 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í stav413
.
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
aPOST
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.