Praktický návod

Jak navrhnout REST API v Symfony

Začni kontraktem, ne kontrolerem. Díky tomu se API dobře používá, testuje i rozšiřuje.

25 minut · Symfony

Nejdřív stručně

Co vlastně stavíš?

API je dohoda, jak si dvě aplikace předávají data. REST API tuto dohodu obvykle staví nad HTTP: URL popisuje zdroj, metoda říká akci a odpověď nese výsledek.

Endpoint je jedna konkrétní adresa API, třeba GET /api/products/42. Vstup i odpověď drž jednoduché a posílej je nejčastěji jako JSON.

Připrav si

Co budeš potřebovat

Stačí funkční Symfony projekt. Než začneš psát kód, napiš si na papír jeden malý případ použití.

Symfony projekt a lokální prostředí, ve kterém spustíš příkaz php bin/console.
Jeden konkrétní zdroj, například produkt nebo objednávku. Nezačínej celým e-shopem.
Představu, kdo API volá a co smí dělat. Přístup a ověření identity doplň hned, ne až po spuštění.
Nástroj pro volání API: pro začátek stačí curl, Postman nebo Insomnia.

Kroky 1 až 3

Navrhni API po malých částech

Nejprve popiš chování. Kód potom jen naplní jasnou dohodu.

1. Popiš zdroje a endpointy

Vyber jeden zdroj, třeba produkt. Jeho kolekce může být /api/products a jeden produkt /api/products/{id}.
Ke čtení použij GET. Pro vytvoření POST. Úpravu a smazání přidej až ve chvíli, kdy je opravdu potřebuješ.
U každého endpointu si napiš: vstup, úspěšnou odpověď, možné chyby a oprávnění. To je tvůj kontrakt.
Route dej přímo ke kontroleru pomocí atributu #[Route]. URL začínej společným prefixem /api.

Oficiální Symfony dokumentace k routám

2. Odděl vstup od databázového modelu

Nenech klienta posílat data rovnou do entity. Vytvoř malý vstupní objekt pro jeden požadavek.
Do něj dej jen pole, která klient smí poslat. Přidej validační pravidla pro povinné hodnoty, délku a formát.
V kontroleru načti JSON, převeď ho na vstupní objekt a validuj ho. Teprve potom zavolej aplikační službu.
Chybný vstup vrať se stavem 400 nebo 422 a s poli, která potřebuje volající opravit.

composer require symfony/validator symfony/serializer

Oficiální Symfony dokumentace k validaci

3. Vracej konzistentní odpovědi

Úspěšnou odpověď vrať jako JSON. Vyber si názvy polí a neměň je bez domluvy s klienty.
Používej význam HTTP metod a stavů: 200 pro čtení, 201 po vytvoření, 404 pro nenalezený zdroj.
Chyby vrať ve stejném tvaru. Přidej stručnou zprávu a stabilní kód, podle kterého je klient pozná.
Citlivé interní výjimky ani databázové chyby do odpovědi neposílej. Zapiš je do logu.

Oficiální Symfony dokumentace ke kontrolerům

Krok 4

Ověř API jako běžný klient

Neověřuj jen „že to projde“. Zkus i situace, které se skutečně stanou.

Zkontroluj zaregistrované cesty

Symfony vypíše všechny route. U svého endpointu si ověř metodu, URL i název.
```
php bin/console debug:router
```
Pošli jeden platný požadavek

Nahraď adresu svou lokální URL. Odpověď má mít očekávaný JSON a správný HTTP stav.
```
curl -i http://localhost:8000/api/products/42
```
Zkus chybný vstup

Pošli chybějící nebo neplatné pole. API nemá spadnout ani vrátit HTML chybovou stránku.
```
curl -i -X POST http://localhost:8000/api/products -H 'Content-Type: application/json' -d '{}'
```

Když to zlobí

Nejčastější chyby

Endpoint vrací HTML místo JSONu

Nejspíš požadavek nedošel do správného kontroleru nebo výjimku zachytil výchozí chybový handler. Ověř route, hlavičku Accept a jednotné zpracování chyb.

php bin/console debug:router

Klient může změnit pole, které změnit nesmí

Nemapuj celý request přímo do entity. Vstupní objekt drž malý a do entity přepisuj jen explicitně povolená pole.

Jednou API vrací chybu jinak než podruhé

Sjednoť odpovědi na chyby na jednom místě. Klient pak nemusí hádat, zda čte message, errors nebo HTML.

Přidáváš verzi API příliš brzy

Nejdřív udrž stabilní kontrakt a jednoduché změny dělej zpětně kompatibilně. Verzi v URL přidej až ve chvíli, kdy opravdu potřebuješ vedle sebe dvě nekompatibilní podoby.

Hotovo

Máš pevný základ API.

REST API teď staví na jasném kontraktu. Další endpointy přidávej stejným rytmem: popsat, validovat, provést akci, vrátit srozumitelný výsledek.

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