Praktický návod

Jak propojit dva systémy přes API

Nejdřív si řekni, kdo vlastní data a kdy se mají změnit. Teprve potom začni psát volání.

25 minut · Integrace systémů

Nejdřív stručně

Co znamená propojit systémy?

API je dohoda, podle které si aplikace předávají data. Jedna strana zveřejní rozhraní, druhá ho volá podle popsaných pravidel. Propojení není jednorázový import; musí fungovat i při běžných změnách a chybách.

REST API běžně používá HTTP adresy a metody jako GET nebo POST. Bezpečnost ale nezačíná URL: ověř, kdo volá, co smí a jak ochráníš přístupové údaje.

Připrav si

Co potřebuješ před prvním propojením

Nejprve si připrav malý a ověřitelný případ. Třeba předání jedné objednávky, ne synchronizaci celé historie.

Oficiální dokumentaci API a testovací účet nebo sandbox, pokud jej poskytovatel má.
Popis jedné události: co ji spustí, jaká data nese a co má druhý systém udělat.
Rozhodnutí, který systém je zdrojem pravdy pro každé předávané pole.
Bezpečné místo pro tokeny a klíče: proměnné prostředí nebo správce tajných údajů, ne repozitář.

Kroky 1 až 3

Postav propojení po malých částech

Dobrý začátek je jedno čtení nebo jeden neškodný zápis. Teprve po ověření přidávej další data a obousměrné změny.

1. Napiš malý kontrakt

Vyber jednu akci, například „vytvoř zákazníka ve druhém systému“. Napiš, kdy přesně se má provést.
Sepiš vstupní pole, povinné hodnoty, úspěšnou odpověď a chyby. Domluvte se i na formátu času a identifikátorech.
Urči, jak poznáš stejný záznam v obou systémech. Interní ID z jednoho systému nemusí dávat smysl v druhém.
Začni jedním směrem. Obousměrná synchronizace přináší konflikty a potřebuje zvláštní pravidla.

Oficiální specifikace OpenAPI

2. Přidej bezpečného API klienta

Zjisti, jak funguje autentizace. Může to být API klíč, OAuth token nebo podepsaný požadavek. Použij přesně postup z dokumentace druhé strany.
URL, timeout, hlavičky a práci s tokenem dej do jedné klientské třídy. Kontroler ani doménová logika nemají znát technické detaily cizí služby.
Před čtením odpovědi zkontroluj HTTP stav. Stav 401, 404 nebo 500 není platná odpověď s prázdnými daty.
Odpověď převeď do vlastního malého datového tvaru. Změna názvu pole u partnera pak neprojde celou aplikací.

composer require symfony/http-client

Oficiální Symfony dokumentace k HTTP klientovi

3. Ošetři chyby a provoz

Nastav rozumný timeout. Čekání desítky sekund na druhý systém často jen zablokuje vlastní uživatele.
Do logu ulož název operace, interní identifikátor, HTTP stav a bezpečnou zprávu. Nikdy celý token ani osobní údaje navíc.
Dočasnou chybu opakuj jen omezeně a s pauzou. Zápis, který by mohl vzniknout dvakrát, musí mít ochranu proti duplicitě.
Připrav způsob, jak chybné předání znovu zpracovat. Uživatel nemá muset objednávku ručně vytvářet podruhé.

Oficiální Symfony dokumentace k opakování požadavků

Krok 4

Ověř propojení na malém vzorku

Nejprve zkoušej v testovacím prostředí. Při prvním provozním spuštění sleduj každý předaný případ.

Zavolej jednoduché čtení

Použij endpoint, který nic nemění. Ověříš URL, síť i přístupové údaje bez zásahu do reálných dat.
```
curl -i https://api.example.com/v1/health
```
Předej jeden testovací záznam

Porovnej hodnoty na obou stranách. Kontroluj hlavně identifikátor, datum, měnu, prázdné hodnoty a zaokrouhlení.
Vyzkoušej špatný token a nedostupnost

Aplikace má chybu srozumitelně zalogovat, neoznačit data jako odeslaná a nabídnout bezpečný další pokus.

Když to zlobí

Nejčastější chyby

API vrací 401 nebo 403

Autentizace a oprávnění nejsou totéž. Ověř formát hlavičky, platnost tokenu a oprávnění účtu k danému endpointu.

Data se po předání liší

Zapiš ukázkový request a response bez tajných údajů. Porovnej typy polí, časová pásma a pravidla, která prázdné hodnoty převádějí na nulu nebo naopak.

Výpadek druhého systému zastaví vlastní aplikaci

Omez čekání a práci, která nemusí proběhnout hned, ulož pro pozdější zpracování. Uživateli jasně řekni, co se podařilo a co čeká.

Stejný záznam se vytvoří dvakrát

Používej stabilní interní identifikátor nebo idempotentní klíč, pokud jej API podporuje. Před dalším pokusem ověř, zda už první opravdu neuspěl.

Hotovo

Propojení má bezpečný základ.

API není jen URL a token. Je to dohoda o datech, chybách a odpovědnosti. Další operace přidávej po jedné.

Přečíst API ve slovníku Všechny návody