API a REST služby: návrh, implementace a správa

Co je API a proč je klíčové

API (Application Programming Interface) je definované rozhraní, které umožňuje aplikacím vzájemně komunikovat. V kontextu webu se nejčastěji jedná o HTTP API, kde klient (prohlížeč, mobilní aplikace, server) odesílá dotazy na konkrétní adresy (URI) a server vrací odpovědi ve strukturovaném formátu (typicky JSON). Dobře navržené API zvyšuje modularitu systémů, urychluje vývoj, usnadňuje integrace a snižuje technologickou závislost mezi týmy.

REST: architektonický styl

REST (Representational State Transfer) není protokol ani knihovna, ale soubor principů pro distribuované systémy nad HTTP. Klíčové body: zdrojově orientovaný model (vše je resource se svou URI), bezstavovost (každý požadavek obsahuje vše potřebné), jednotné rozhraní (standardní metody a kódy), cacheovatelnost a ideálně hypermedia jako řídící prvek stavu aplikace (HATEOAS).

Resource-first návrh a URI

Substantiva, nikoli slovesa: /orders, /customers/123 místo /createOrder.
Hierarchie a vztahy: /customers/123/orders (vnořený kontext), s odkazy v odpovědi na související zdroje.
Filtrace a stránkování: dotazovací parametry (například ?status=paid&limit=50&offset=100).
Stabilita: URI by měla být trvalá; verzování řešte jinak než v názvu zdroje, viz sekce o verzování.

HTTP metody a jejich sémantika

GET: načítání zdrojů; bezpečná a idempotentní metoda.
POST: vytvoření nebo ne-idempotentní operace (např. spuštění workflow). Vytvořený zdroj vraťte s 201 Created a hlavičkou Location.
PUT: úplná idempotentní aktualizace reprezentace zdroje.
PATCH: částečná aktualizace (např. JSON Patch); nemusí být idempotentní, ale je to doporučeno.
DELETE: odstranění zdroje; idempotentní (opakované volání nesmí způsobit škody).
HEAD/OPTIONS: metadata a vyjednání možností (CORS, Allow).

HTTP stavové kódy a konzistentní chybové zprávy

2xx: 200 OK, 201 Created, 204 No Content.
3xx: přesměrování (méně časté v API).
4xx: chyba na straně klienta – 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity, 429 Too Many Requests.
5xx: chyba na straně serveru – 500, 502, 503.

Formát chybových zpráv: sjednoťte schéma, například { "type": "https://errors.example.com/validation", "title": "Validation error", "detail": "...", "instance": "/orders/abc", "errors": { "customerId": ["Required"] } } a přidejte korelační ID v hlavičce (Trace-Id).

Reprezentace a vyjednávání obsahu

Preferovaným formátem je JSON (Content-Type: application/json). Využijte content negotiation prostřednictvím hlavičky Accept, případně využijte alternativní reprezentace (CSV, iCal). Omezte „magické“ formáty v query parametrech; formální vyjednávání je srozumitelnější a lépe cacheovatelné.

HATEOAS a hypermedia

Odpovědi mohou obsahovat odkazy (_links) a akce (_actions), které vedou klienta. Například u objednávky se status=NEW poskytněte odkaz approve, u status=PAID odkaz refund. Hypermedia snižuje coupling klienta na interní workflow.

Idempotence a bezpečnost operací

U plateb a provozně citlivých volání zavádějte idempotency keys (hlavička Idempotency-Key) u POST, aby opakované pokusy nevedly k duplicitám. Definujte časové okno a deterministické odpovědi.

Cache, ETagy a podmíněné požadavky

Vracejte ETag nebo Last-Modified a podporujte hlavičky If-None-Match / If-Modified-Since pro 304 Not Modified.
Nastavte Cache-Control (například public, max-age=60) – snižuje latenci i zátěž serveru.
U necacheovatelných odpovědí používejte no-store (například u osobních dat).

Stránkování, třídění a projekce

Cursor-based pagination: stabilnější než offset/limit; vracejte kurzory next/prev.
Třídění a filtry: například ?sort=-createdAt,price&status=paid.
Výběr polí (projekce): ?fields=id,status,total pro menší objemy dat.

Autentizace, autorizace a bezpečnost

OAuth 2.1 / OIDC: pro delegovaná práva a přístup třetích stran; používejte standardní toky (Authorization Code s PKCE).
JWT přístupové tokeny: krátká expirace, audience, issuer, rotace klíčů (JWKS). Pro dlouhé relace používejte refresh token mimo prohlížečový kontext.
Scope/role model: granulární oprávnění, atributová autorizace (ABAC) pro scénáře RLS.
Transport: vždy HTTPS, HSTS, bezpečné cookies (HttpOnly, Secure) a ochrana proti CSRF u cookie-based autentizace.
Vstupní validace a limity: omezení velikosti těla požadavku (max body size), validace podle schématu, ochrana proti JSON injection.
Rate limiting & throttling: standardizujte hlavičky (RateLimit-Limit, -Remaining, -Reset), používejte exponenciální zpomalování, soft a hard kvóty.

CORS a integrace webového frontendu

Prohlížeče nastavte řízené CORS: Access-Control-Allow-Origin (nikoli * u privátních API), Allow-Credentials dle potřeby a minimalizujte množinu metod/hlaviček v Access-Control-Allow-Methods / -Headers. Preflight odpovědi cacheujte (Access-Control-Max-Age).

Verzování a kompatibilita

Bezpečná evoluce: přidání polí zpravidla znamená zpětnou kompatibilitu; odebrání nebo změna významu pole jsou breaking changes.
Způsoby verzování: hlavička Accept: application/vnd.example.v2+json (content negotiation), méně často /v1 v URI. Preferujte řízení přes kontrakt a schéma.
Deprecation policy: oznamujte v hlavičkách (Deprecation, Sunset), poskytněte migrační průvodce a sandbox prostředí.

Specifikace: OpenAPI/Swagger, JSON Schema

Formální kontrakt zvyšuje kvalitu i automatizaci. OpenAPI definuje operace, schémata, bezpečnost a odpovědi; JSON Schema slouží k validaci. Z kontraktu generujte klientská SDK, serverové stuby, testy a dokumentaci. Udržujte kontrakt jako jediný zdroj pravdy (design-first nebo code-first s kvalitní synchronizací).

Dokumentace a DX (Developer Experience)

Referenční dokumentace: jasný popis polí, příklady requestů/response, chybové kódy.
Tutoriály a „quickstarty“: funkční ukázky v populárních jazycích, Postman kolekce, curl snippet.
Portál a klíče: samoobslužná registrace, rotace klíčů, přehled limitů a využití API.

Testování: smluvní testy, integrace a výkon

Contract testing: testy spotřebitel–poskytovatel (např. Pact), aby změny nerozbily klienty.
Integrační testy: vůči skutečnému runtime (Testcontainers), seed dat a chybové scénáře.
Zátěž a latence: definujte cíle SLO, testujte p99/p999 latenci, implementujte chaos testy pro odolnost.

Provoz, observabilita a správa

Logování a tracing: korelační ID, strukturované logy, distribuované trasování (W3C Trace Context).
Metriky: počet požadavků za sekundu (QPS), chybovost, latence, využití limitů; alarmy na porušení SLO.
API brány a registry: autentizace, limity, transformace, směrování verzí, publikace do katalogu služeb.
Rollback a canary: postupné nasazení, feature flagy, zachování kompatibility schémat při migracích databází.

Antipatterny a časté chyby

RPC převlečené za REST: endpointy typu /doAction bez zdrojů a bez sémantiky HTTP metod.
„Chattiness“: příliš mnoho malých dotazů; řešte pomocí embedding a expand parametrů (?include=items,customer) nebo batch endpointů.
Nedeterministické chyby: nekonzistentní status kódy a nejednotný formát chybových zpráv.
Přetěžování GET: měnění stavu přes GET (porušení bezpečnosti metody) a absence cache hlaviček.

REST vs. GraphQL vs. gRPC: kdy co zvolit

REST: jednoduchý, cacheovatelný, výborně využitelný přes CDN; ideální pro veřejná API a integrační vrstvy.
GraphQL: flexibilní dotazování a projekce dat, méně „chattiness“ pro komplexní klienty; vyšší nároky na bezpečnost a výkon resolverů.
gRPC: binární Protobuf, plně duplexní komunikace, nízká latence; vhodné pro mikroservisy a interní komunikaci, méně vhodné pro prohlížeče bez gateway.

Model zralosti REST (Richardson Maturity Model)

Úroveň 0: jediné endpointy fungující jako „tunel“ přes HTTP.
Úroveň 1: zavedení zdrojů.
Úroveň 2: správná implementace HTTP metod a stavových kódů.
Úroveň 3: hypermedia řízená stavem (HATEOAS).

Praktický návrhový checklist

Identifikujte doménové zdroje a jejich vztahy; navrhněte stabilní a srozumitelné URI.
Zajistěte, aby metody a stavové kódy odpovídaly správné sémantice.
Zaveďte jednotný chybový formát a korelační ID pro lepší traceovatelnost.
Specifikujte kontrakt (OpenAPI) a automatizujte validace.
Implementujte bezpečnostní mechanismy (OAuth/OIDC, TLS), rate limiting a auditní záznamy.
Optimalizujte přenos dat (projekce polí, komprese, cache, ETagy).
Zajistěte stránkování, filtry a třídění s konzistentní syntaxí.
Nastavte observabilitu, definujte SLO a plánujte release strategii (canary, rollback).
Plánujte evoluci API: verzování, deprecations, migrační průvodce.

Závěr

API a REST služby tvoří páteř moderních digitálních ekosystémů. Úspěch stojí na pevných základech HTTP sémantiky, doménovém návrhu, bezpečnosti, kontraktově řízeném vývoji a provozní disciplíně. Kombinací ověřených principů (resource-first, idempotence, cache) s kvalitní vývojářskou zkušeností (OpenAPI, automatizace, portál) lze budovat rozšiřitelná a dlouhodobě udržitelná rozhraní – ať už pro veřejné integrace, interní mikroservisy či mobilní a webové klienty.