REST API
Také známé jako: RESTful API, REST rozhraní
REST API je nejrozšířenější způsob, jak stavět webová rozhraní: každý typ dat má vlastní adresu a operace se vyjadřuje metodou HTTP požadavku. Naprostá většina e-shopových platforem nabízí právě tuhle podobu API.
Kdy to potřebuješ vědět
Pokaždé, když stavíš nebo ladíš vlastní napojení. Základní logika je jednoduchá a znalost návratových kódů ušetří většinu času při hledání chyb.
Jak to funguje
Adresa říká, s jakým typem dat pracuješ — produkty, objednávky, kategorie. Metoda říká, co se má stát. Kombinace obojího je celý požadavek.
Odpověď má vždy návratový kód. Ten je důležitější než samotná data, protože rozhoduje o tom, co má integrace udělat dál:
- 2xx — uspělo.
- 4xx — chyba na tvé straně: špatná data, chybějící oprávnění, překročený limit. Opakování téhož požadavku nepomůže.
- 5xx — chyba na straně serveru. Tady opakování s odstupem smysl má.
Rozdíl mezi 4xx a 5xx je to, co odlišuje integraci, která se sama zotaví, od té, která se zasekne v nekonečné smyčce.
Nejčastější chyby
- Ignorování návratových kódů. Integrace tvrdí, že proběhla, a přitom nic nezapsala.
- Opakování požadavku po chybě 4xx. Data jsou špatně, opakováním se nespraví — a u limitů to situaci zhorší.
- Neposílání hlavičky s typem obsahu. Server neví, jak tělo požadavku číst, a odmítne ho.
- Načítání po jedné položce. Funguje na testu s deseti produkty a rozpadne se na deseti tisících.
Shoptet a Upgates
Upgates. API v2 je REST rozhraní; metody POST, GET, PUT a DELETE, přepis metody přes hlavičku X-HTTP-Method-Override. Chybové odpovědi obsahují pole messages s informací, který objekt a která vlastnost je špatně. Stavové kódy zahrnují 200, 301 (nová adresa v Location), 400, 401, 403, 404, 405, 413, 429, 500 a 501. K dispozici je PHP klient. (Ověř aktuální stav.)
Časté otázky
Co znamená chyba 429?
Překročil jsi limit počtu požadavků. Odpověď obvykle obsahuje informaci, kdy to zkusit znovu — a opakovat dřív nemá smysl.
Jaký je rozdíl mezi PUT a POST?
POST zakládá novou položku, PUT upravuje existující. Zaměnit je znamená buď duplicity, nebo neúspěšné zápisy.
Proč dostávám 413?
Poslal jsi v jednom požadavku víc položek, než rozhraní povoluje. Dávka se musí rozdělit.
Související pojmy
- API – API je rozhraní, přes které spolu programy komunikují přímo, bez člověka a bez souborů. U e-shopu umožňuje číst a měnit data v reálném čase — vytvořit objednávku, upravit sklad, načíst produkty — na rozdíl od feedu, který je jednosměrný snímek.
- GraphQL – GraphQL je alternativa k REST API, kde si volající v dotazu sám určí, která pole chce dostat zpět. Místo pevně daných odpovědí na pevných adresách posílá dotaz na jedinou adresu a dostane přesně to, co si vyžádal.
- Webhook – Webhook je notifikace, kterou systém sám odešle ve chvíli, kdy nastane určitá událost — vznikne objednávka, změní se produkt, aktualizuje se sklad. Nahrazuje pravidelné dotazování: místo aby se integrace ptala „změnilo se něco?", dozví se to, až když se skutečně něco stane.
- Rate limit – Rate limit je omezení počtu požadavků, které smí jedna integrace na rozhraní poslat za daný čas. Chrání server před přetížením a u e-shopových platforem bývá navázaný na tarif — takže víc integrací znamená dělit se o stejný rozpočet požadavků.
- API klíč – API klíč je přístupový údaj, kterým se integrace prokazuje při komunikaci s rozhraním. Určuje nejen to, kdo se připojuje, ale i co smí — a proto by měl mít každé napojení vlastní klíč s minimem oprávnění.
- Napojení ERP – Napojení ERP je propojení e-shopu s podnikovým systémem tak, aby si vyměňovaly data automaticky — typicky objednávky z e-shopu do ERP a sklad s cenami z ERP na e-shop. Realizuje se buď hotovým doplňkem, nebo vlastní integrací přes API.
Další pojmy ze skupiny Feedy & integrace
- APIAPI je rozhraní, přes které spolu programy komunikují přímo, bez člověka a bez souborů. U e-shopu umožňuje číst a měnit data v reálném čase — vytvořit objednávku, upravit sklad, načíst produkty — na rozdíl od feedu, který je jednosměrný snímek.
- API klíčAPI klíč je přístupový údaj, kterým se integrace prokazuje při komunikaci s rozhraním. Určuje nejen to, kdo se připojuje, ale i co smí — a proto by měl mít každé napojení vlastní klíč s minimem oprávnění.
- Datová migraceDatová migrace je převod obsahu e-shopu z jednoho systému do druhého — produktů, kategorií, zákazníků, objednávek a jejich vzájemných vazeb. Nejtěžší na ní nejsou samotná data, ale vazby mezi nimi a pole, která v cílovém systému nemají protějšek.
- Diagnostika feeduDiagnostika feedu je pravidelná kontrola toho, kolik produktů kanál z feedu skutečně přijal, kolik jich zamítl a proč. Je to jediný způsob, jak zjistit, že část sortimentu tiše vypadla — počet položek ve feedu totiž neříká nic o tom, kolik se jich reálně zobrazuje.
- ERPERP je podnikový systém, ve kterém firma vede sklad, objednávky, fakturaci a účetnictví na jednom místě. U e-shopu bývá zdrojem pravdy o skladu a cenách, zatímco e-shop je prodejní kanál — a rozhodnutí, který systém co určuje, je základ jakéhokoli napojení.
- Export produktůExport produktů je vytažení dat z katalogu do souboru nebo rozhraní pro použití jinde — pro srovnávače, pro účetnictví, pro dodavatele nebo jako záloha před hromadnou úpravou. Na rozdíl od feedu nemusí mít pevnou strukturu danou cizím systémem.