API Design

API je rozhraní, přes které tvůj backend nabízí svoje funkce okolnímu světu, frontendu, mobilní aplikaci, jiné službě. Je to smlouva: „když mi pošleš tenhle požadavek, udělám tohle a vrátím ti tamto." A jakmile tu smlouvu někdo začne používat, nemůžeš ji jen tak změnit, aniž bys mu rozbil aplikaci. Dobrý návrh API je hlavně o ohleduplnosti k tomu, kdo ho bude volat.

Pár pojmů na úvod

• API (Application Programming Interface) = sada „vstupních bodů" tvého backendu, které může někdo zavolat. Ne pro člověka jako web, ale pro jiný program.
• Endpoint = jeden konkrétní vstupní bod = kombinace cesty a metody, např. GET /courses nebo POST /orders.
• Zdroj (resource) = věc, se kterou API pracuje (kurz, objednávka, uživatel).
• Payload / tělo (body) = data, která v requestu posíláš nebo v response dostáváš (obvykle JSON).
• Klient (konzument API) = ten, kdo tvoje API volá. Může to být tvůj vlastní frontend i cizí appka.

Vycházíme z Foundations. HTTP metody a status kódy už znáš, teď je použijeme k návrhu rozumného API.

Styly API, tři přístupy

Existují tři hlavní způsoby, jak API postavit. Nejsou to soupeři, každý se hodí jinam:

Jako junior začni s REST, je nejrozšířenější a všechno ostatní pochopíš snáz, až ho budeš mít v ruce. gRPC a GraphQL si necháš, až narazíš na konkrétní potřebu.

REST pořádně

Hlavní myšlenka REST: zdroj je podstatné jméno, akci určuje HTTP metoda. Do URL tedy nepatří slovesa, co s daným zdrojem děláš, říká už metoda (GET, POST…).

✅ GET    /courses             vrať seznam kurzů
✅ GET    /courses/42          vrať detail kurzu 42
✅ POST   /courses             vytvoř kurz
✅ PUT    /courses/42          nahraď celý kurz 42
✅ PATCH  /courses/42          uprav část kurzu 42
✅ DELETE /courses/42          smaž kurz 42
✅ GET    /courses/42/lessons  lekce patřící ke kurzu 42

❌ GET  /getCourses            (sloveso v URL: to dělá GET)
❌ POST /createCourse          (sloveso v URL: to dělá POST)
❌ POST /courses/42/delete     (na mazání je DELETE)

Připomenutí sémantiky metod (z Foundations): GET jen čte (nic nemění, jde cachovat), PUT a DELETE jsou idempotentní (zopakování nic nezkazí), POST idempotentní není a právě proto existují idempotency keys ↓.

Idempotency keys, jak bezpečně opakovat POST

Připomeň si pojem idempotentní z Foundations: operace, kterou můžeš provést vícekrát se stejným výsledkem. Problém je, že POST (vytvoř něco) idempotentní není.

Představ situaci: klient pošle POST /payments, ale spojení vyprší (timeout) dřív, než dorazí odpověď. Klient neví, jestli platba proběhla. Co udělá? Zkusí to znovu (retry) a když ta první ve skutečnosti prošla, právě jsi zákazníkovi naúčtoval dvakrát.

Řešení: klient ke každému takovému requestu přiloží unikátní klíč (Idempotency-Key). Server si podle něj pozná, že už ten požadavek viděl:

Server si páruje klíč → výsledek (třeba v Redisu nebo databázi, na omezenou dobu). Podrobně, včetně záludností, v kapitole Patterny → Idempotency. Tohle je naprostý základ, který by měl umět každý backend engineer.

Verzování, jak měnit API a nerozbít staré klienty

Tvoje API se bude vyvíjet, ale aplikace, které ho už používají, nesmí ze dne na den přestat fungovat.

• Přes URL: /v1/courses, /v2/courses, nejjasnější a nejčastější způsob.
• Přes hlavičku: verzi pošleš v hlavičce requestu, čistší URL, ale hůř vidět.
• Pravidlo: přidat nové (volitelné) pole je neškodné. Odebrat nebo přejmenovat pole, nebo změnit jeho typ, je breaking change (rozbije klienty) → dělej to v nové verzi.

⚠️ Nová major verze není zadarmo, znamená udržovat dvě implementace souběžně. Proto se s ní šetří: většina změn jde udělat zpětně kompatibilně (aditivně), bez nové verze. A když starou verzi rušíš, udělej to řízeně: ohlas to dopředu (hlavičky Deprecation/Sunset) a dej klientům čas přejít. Neverzuj při každé změně.

Pagination, nikdy nevracej „všechno"

Kdyby GET /orders vrátilo všech 5 milionů objednávek, zabiješ tím databázi i klienta. Proto se výsledky vrací po stránkách (pagination). Dva způsoby:

Pro nekonečný scroll a velké tabulky používej cursor. Offset si nech na malé, neměnné seznamy.

Error contract, jednotný tvar chyb

Klient musí umět chybu zpracovat strojově, ne jen přečíst. Proto vracej chyby pořád ve stejném tvaru napříč celým API:

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Vstup neprošel validací",
    "details": [{ "field": "email", "issue": "invalid_format" }]
  }
}

• code je stabilní řetězec pro stroj (kód na něj může reagovat), message je text pro člověka. Klientovi nikdy neposílej syrový technický výpis chyby (stack trace), je to únik informací a bezpečnostní riziko.
• Vracej k tomu správný HTTP status (4xx = chyba klienta, 5xx = chyba serveru).
• Pole details patří k validačním chybám (422, které konkrétní pole je špatně). Business konflikt (409, např. „kurz je plný") nemá konkrétní vadné pole, vrať jen code a message (třeba code: "COURSE_FULL"), žádné details necpi.

Další věci, co dělají API dobrým

• Konzistentní pojmenování: vyber si snake_case nebo camelCase a drž ho všude stejně.
• Filtrování a řazení přes query parametry: ?status=active&sort=-createdAt.
• Rate limiting: omez počet requestů na klienta, ať ti někdo API nezahltí; přes kód 429 (Security).
• Dokumentace: popiš API standardem OpenAPI/Swagger, ideálně generovaným z kódu, ať nezestárne.
• Bezpečnost: každou operaci, co mění data, ověř (kdo a jestli smí), vstup validuj na serveru a nikdy nevěř tomu, co přijde od klienta (viz Security).

Bulk operace, dlouhé operace a API gateway

Tři situace, na které REST „základ" nestačí a je dobré vědět, jak na ně:

• Bulk operace (hromadné). Potřebuješ vytvořit/upravit 100 položek? Posílat 100 requestů je pomalé. Nabídni endpoint, který vezme pole položek najednou. Pak ale řeš částečný úspěch, co když projde 98 a 2 selžou? Vrať výsledek pro každou položku zvlášť, ne jen „OK / chyba".
• Dlouhé operace (async API). Když operace trvá dlouho (vygenerovat velký report), nenech klienta čekat na jednu odpověď. Vrať hned 202 Accepted s odkazem „stav úlohy je tady", úlohu zpracuj na pozadí a klient si stav buď polluje (občas se zeptá), nebo mu po dokončení pošleš webhook.
• API gateway. Když máš víc služeb, postavíš před ně jednu bránu, která řeší společné věci na jednom místě: ověření, rate limiting, směrování requestů na správnou službu. Klient mluví s bránou, ne přímo se službami. (Varianta BFF = Backend For Frontend: brána ušitá na míru konkrétnímu klientovi, třeba mobilu.)

Failure modes, kde se to nejčastěji pokazí

• Chybějící idempotency → duplicitní platby/objednávky, když klient po timeoutu zopakuje request.
• Breaking change bez nové verze → rozbiješ produkční klienty bez varování.
• Offset pagination na milionech řádků → pomalé a přeskakující/duplikující záznamy.
• Únik interních detailů v chybách → posíláš klientovi stack trace nebo SQL = bezpečnostní díra.

🛠️ Cvičení

1. Navrhni REST API. Pro „kurzy a jejich lekce" napiš endpointy: výpis a detail kurzu, vytvoření a úprava kurzu, výpis lekcí kurzu a zápis studenta. Bez sloves v URL, se správnými metodami a status kódy.
2. Idempotentní POST. Naskicuj v pseudokódu handler POST /payments s Idempotency-Key: kde klíč ukládáš, jak poznáš opakovaný request a jak vrátíš uloženou odpověď.
3. Cursor vs offset. Pro nekonečný scroll feedu napiš, jaké query parametry použiješ, a vysvětli, proč offset na milionu řádků začne přeskakovat nebo duplikovat záznamy.
4. Error contract. Navrhni jednotný tvar chyby a přiřaď k němu 4 situace i s HTTP kódy: neprošla validace, nepřihlášen, nemá právo, konflikt (např. plný kurz).
5. Breaking change? U každé změny rozhodni, jestli je breaking (a tedy potřebuje novou verzi): přidání volitelného pole, přejmenování pole, zúžení typu, nový povinný parametr, změna formátu data.

🧠 Otázky & odpovědi