Praktický návod

Jak vytvořit API klienta v PHP

Schovej HTTP detaily do jedné malé třídy. Zbytek aplikace pak pracuje s vlastními daty, ne s cizím API.

25 minut · PHP

Nejdřív stručně

Co má API klient dělat?

API klient je část aplikace, která sestaví HTTP request, odešle ho vzdálenému serveru a přeloží response do tvaru, kterému rozumí tvůj kód.

Dobrá hranice mezi klientem a serverem drží URL, hlavičky, autentizaci a cizí názvy polí na jednom místě. Volající dostane vlastní datový objekt nebo srozumitelnou výjimku.

Připrav si

Co budeš potřebovat

Začni jednou bezpečnou čtecí operací. Než napíšeš klienta pro celé API, ověř si jeden skutečný request a response.

PHP 8.2 nebo novější a Composer.
Oficiální dokumentaci API: základní URL, endpoint, metodu, autentizaci, chybové stavy a příklad odpovědi.
Testovací účet nebo token uložený v proměnné prostředí. Tajný údaj nepatří do zdrojového kódu ani logu.
Jednu malou operaci, například načtení produktu podle ID, a ukázkovou úspěšnou i chybovou odpověď.

Kroky 1 až 3

Postav klienta s jasnou hranicí

HTTP knihovna vyřeší přenos. Tvoje třída musí vyřešit kontrakt, chyby a převod dat.

1. Nainstaluj HTTP klienta a nastav společné volby

Použij udržovanou knihovnu místo vlastního obalování cURL. Symfony HttpClient funguje i mimo Symfony projekt.
Na jednom místě nastav základní URL, hlavičku Accept, autentizaci a krátký timeout. URL ani token neopakuj v každé metodě.
Rozliš timeout jednoho síťového kroku a maximální dobu celé operace. Vzdálená služba nesmí držet PHP proces neomezeně.
Token posílej v odpovídající HTTP hlavičce podle dokumentace poskytovatele a nikdy ho nezapisuj do logu.

composer require symfony/http-client

Oficiální Symfony dokumentace k HTTP klientovi

2. Vytvoř jednu třídu pro vzdálené API

Pojmenuj klienta podle služby, například CatalogApiClient. Jeho veřejné metody mají popisovat operace, ne HTTP detaily.
Request sestav uvnitř klienta. Parametry URL escapuj a query předávej přes volbu query, ne ručním skládáním řetězce.
Nejdřív přečti HTTP stavový kód. Stav 404 může znamenat nenalezený výsledek, zatímco 401, 429 a 5xx mají vést k různým chybám.
JSON response převeď do vlastního DTO a ověř povinná pole i datové typy. Cizí asociativní pole nenech protékat celou aplikací.

$http = HttpClient::createForBaseUri($_ENV['CATALOG_API_URL'], [
    'auth_bearer' => $_ENV['CATALOG_API_TOKEN'],
    'headers' => ['Accept' => 'application/json'],
    'timeout' => 5,
    'max_duration' => 10,
]);

$response = $http->request('GET', '/v1/products/42');
$status = $response->getStatusCode();
$data = $response->toArray(false);

Oficiální dokumentace k odesílání requestů

3. Navrhni chyby, opakování a logování

Přelož síťovou chybu, timeout a neplatnou response na vlastní výjimky. Volající pak nemusí znát výjimky konkrétní knihovny.
Retry používej jen u dočasných chyb, omezeně a s prodlužující se pauzou. U stavu 429 respektuj Retry-After.
Zápisové requesty automaticky neopakuj, pokud služba negarantuje idempotenci nebo nepodporuje idempotency key. Jinak můžeš vytvořit duplicitní platbu či objednávku.
Loguj operaci, dobu trvání, HTTP stav a bezpečný correlation ID. Tělo s osobními údaji a autorizační hlavičku vynech.

Oficiální dokumentace k opakování requestů

Krok 4

Ověř klienta proti kontraktu

Test úspěšné odpovědi nestačí. Klient musí předvídat i pomalou, chybnou a neúplnou response.

Spusť neškodný smoke test

Zavolej jeden čtecí endpoint v testovacím prostředí. Zkontroluj výsledné DTO, HTTP stav a to, že log neobsahuje token.
```
php scripts/catalog-api-smoke-test.php
```
Nahraď transport testovací implementací

V jednotkovém testu vrať připravené odpovědi 200, 404, 429 a 500. Ověř přesný request a veřejné chování klienta bez skutečné sítě.
```
vendor/bin/phpunit tests/Integration/CatalogApiClientTest.php
```
Nasimuluj poškozenou response

Vrať neplatný JSON nebo vynech povinné pole. Klient má skončit řízenou výjimkou, ne upozorněním o chybějícím indexu.

Když to zlobí

Nejčastější chyby

Klient čeká příliš dlouho

Nastav timeout i maximální dobu requestu a měř trvání. Vyšší timeout obvykle jen oddálí stejnou chybu.

Chybová response se tváří jako běžná data

Před mapováním těla explicitně rozhodni podle HTTP stavu. Pro očekávané stavy vrať výsledek nebo vlastní doménovou výjimku.

Token se objevil v logu

Rediguj Authorization a další tajné hlavičky už v centrálním loggeru. Neloguj celé objekty requestu ani response.

Změna cizího pole rozbije několik částí aplikace

Mapuj response do vlastního DTO uvnitř klienta. Změnu názvu pole pak opravíš a otestuješ na jednom místě.

Hotovo

API klient má pevnou hranici.

API teď voláš přes jednu testovatelnou vrstvu. Další operace přidávej po jedné a u každé přesně popiš request, response a chybové chování.

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