Jan Mikoláš
Praktický návod
Jak napojit e-shop na externí API
Nezačínej voláním z kontroleru. Nejprve si ujasni data, odpovědnost a chování při výpadku.
Nejdřív stručně
Co znamená napojení na API?
API je smlouva mezi systémy. Při integraci e-shopu si například předáváte sklad, ceny, objednávky nebo zákazníky. Smlouva říká, jaká data poslat, jak je zabezpečit a co znamená odpověď.
Webhook je opačný směr: externí služba sama oznámí změnu tobě. Pro pravidelné čtení dat ale e-shop obvykle používá odchozí HTTP požadavek.
Připrav si
Co potřebuješ před prvním voláním
Dobrá integrace začíná otázkami. Na většinu drahých chyb narazíš ještě před kódem.
- Oficiální dokumentaci externího API a přístup do jeho testovacího prostředí, pokud ho poskytuje.
- Testovací účet nebo API klíč. Tajné údaje ulož do proměnných prostředí, ne do repozitáře.
- Seznam dat, která opravdu potřebuješ přenášet, a systém, který je pro každé z nich zdrojem pravdy.
- Místo pro logy a způsob, jak se dozvíš o chybě dřív než zákazník.
Kroky 1 až 3
Postav integraci, která přežije běžný provoz
Externí služba je mimo tvoji kontrolu. Počítej s pomalou odpovědí, výpadkem i změnou dat.
1. Přečti kontrakt a zmenši úkol
- Vyber jednu malou operaci: třeba načtení skladu jednoho produktu. Neobjednávej, nesynchronizuj ceny a sklad najednou.
- Poznamenej si URL, metodu, povinné hlavičky, vstup, odpověď a chybové stavy.
- Zjisti, jak funguje autentizace: API klíč, OAuth token nebo podpis. Nehádej; řiď se dokumentací poskytovatele.
- Zjisti také pravidla rate limitingu. Limit není chyba, kterou máš přetlačit více požadavky.
2. Vytvoř samostatného klienta
- Volání externí služby schovej do jedné třídy, například SupplierApiClient. Kontroler ani entita nemá znát URL ani hlavičky dodavatele.
- Nastav základní URL, časový limit a autentizaci na jednom místě. Při změně dodavatele pak nehledáš stejné údaje po celém projektu.
- Zkontroluj HTTP stav ještě před čtením odpovědi. Neúspěch 401, 404 nebo 500 neber jako běžná data.
- Převáděj odpověď dodavatele do vlastního malého datového tvaru. Zbytek e-shopu tak nezávisí na jeho názvech polí.
composer require symfony/http-client3. Počítej s chybami a opakováním
- Ulož si do logu bezpečné údaje: název operace, stav odpovědi, čas a interní identifikátor. Nikdy neheslo ani celý token.
- U dočasných chyb použij omezený počet opakování s pauzou. Neopakuj slepě požadavky, které by mohly vytvořit druhou objednávku.
- Pokud externí služba posílá změny přes webhook, přijmi ho rychle a další práci předej na pozadí.
- Měř počet chyb a pomalých odpovědí. Integrace, o které nevíš, že nefunguje, zákazníkovi nepomůže.
Krok 4
Ověř integraci dřív, než jí svěříš objednávky
Začni neškodným čtením dat. Teprve pak zkoušej změny na testovacích datech.
-
Ověř přihlašovací údaje
Zavolej jednoduchý čtecí endpoint. Odpověď 401 nebo 403 znamená problém s identitou nebo oprávněním, ne s daty produktu.
-
Porovnej jednu odpověď s dokumentací
Zkontroluj datové typy, prázdné hodnoty a časová pásma. Jeden ručně ověřený produkt odhalí mnoho chybných předpokladů.
-
Nasimuluj chybu
Zkus špatný token, pomalou odpověď nebo stav 429. E-shop má chybu zachytit, zalogovat a nepoškodit vlastní data.
Když to zlobí
Nejčastější chyby
API vrací 401 nebo 403
Autentizace a oprávnění jsou dvě různé věci. Ověř, zda posíláš správný typ hlavičky, zda token nevypršel a zda účet smí volat daný endpoint.
Narážíš na 429 Too Many Requests
Rate limiting říká, že voláš příliš rychle. Čti hlavičky odpovědi, sniž souběh, používej stránkování a další pokus odlož.
Dodavatel změnil strukturu odpovědi
Nenech jeho odpověď protékat celým e-shopem. Převod v jednom klientovi izoluje změnu a test nad uloženou ukázkovou odpovědí ji zachytí rychleji.
Výpadek API zastaví objednávku
Rozhodni, co je nutné hned a co může počkat. Méně důležitou práci ulož k pozdějšímu zpracování a zákazníkovi dej jasnou informaci.
Hotovo
Integrace má bezpečný základ.
Teď přidávej další operace po jedné. Každá by měla mít jasný kontrakt, ochranu tajných údajů, logy a plán pro výpadek.