API a REST služby – Európska ekonomika

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 jde nejčastěji o HTTP API, kde klient (prohlížeč, mobilní aplikace, server) posí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 nese vše potřebné), jednotné rozhraní (standardní metody a kódy), cacheovatelnost, a ideálně hypermedia jako motor stavu aplikace (HATEOAS).

Resource-first návrh a URI

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

HTTP metody a sémantika

GET: čtení zdrojů; bezpečná a idempotentní.
POST: vytvoření nebo ne-idempotentní operace (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); není nutně idempotentní, ale doporučeno.
DELETE: odstranění zdroje; idempotentní (opakované volání nesmí škodit).
HEAD/OPTIONS: metadata a vyjednání možností (CORS, Allow).

HTTP status 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 klienta – 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity, 429 Too Many Requests.
5xx: chyba serveru – 500, 502, 503.

Chybový formát: sjednoťte schéma, např. { "type": "https://errors.example.com/validation", "title": "Validation error", "detail": "...", "instance": "/orders/abc", "errors": { "customerId": ["Required"] } } a přidejte korelovací 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 přes hlavičku Accept, případně alternativní reprezentace (CSV, iCal). Omezte „magické“ formáty v query parametrech; formální vyjednávání je srozumitelnější a cacheovatelnější.

HATEOAS a hypermedia

Odpovědi mohou obsahovat odkazy (_links) a akce (_actions) pro navádění klienta. Např. u objednávky s status=NEW poskytněte odkaz approve, u status=PAID refund. Hypermedia snižuje coupling klienta na interní workflow.

Idempotence a bezpečnost operací

U plateb a provozně citlivých volání zaveďte idempotency keys (hlavička Idempotency-Key) pro POST, aby opakované pokusy nevedly k duplicitám. Udržujte definované časové okno a deterministické odpovědi.

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

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

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

Cursor-based pagination: lepší pro stabilitu výsledků než offset/limit; vracejte next/prev kurzory.
Třídění a filtry: např. ?sort=-createdAt,price&status=paid.
Field selection (projekce): ?fields=id,status,total pro menší payloady.

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 raději refresh token mimo prohlížečový kontext.
Scope/role model: granulární oprávnění, atributová autorizace (ABAC) pro RLS scénáře.
Transport: vždy HTTPS, HSTS, bezpečné cookies (HttpOnly, Secure), ochrana proti CSRF u cookie-based auth.
Vstupní validace a limity: velikost těla (max body size), validace schématem, ochrana proti JSON injection.
Rate limiting & throttling: standardizujte hlavičky (RateLimit-Limit, -Remaining, -Reset), exponenciální backoff, soft/hard kvóty.

CORS a integrace webového frontendu

Pro prohlížeče nastavte řízené CORS: Access-Control-Allow-Origin (nikoli * pro privátní 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ávat pole je obvykle backward compatible; odstraňování nebo změna významu pole je breaking.
Způsoby verzování: hlavička Accept: application/vnd.example.v2+json (content negotiation), méně často /v1 v URI. Upřednostněte kontraktuální řízení přes schéma.
Deprecation policy: oznamte v hlavičkách (Deprecation, Sunset), poskytněte migrační průvodce a sandbox.

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é stubs, testy a dokumentaci. Udržujte kontrakt jako zdroj pravdy (design-first nebo code-first s kvalitní synchronizací).

Dokumentace a DX (Developer Experience)

Referenční dokumentace: jasná pole, příklady request/response, kódy chyb.
Tutoriály a „quickstarty“: funkční vzorky v populárních jazycích, Postman kolekce, curl snippet.
Portál a klíče: self-service registrace, rotace klíčů, přehled limitů a využití.

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

Contract testing: spotřebitel–poskytovatel (Pact), aby změny nerozbily klienty.
Integrační testy: proti reálnému runtime (Testcontainers), seed dat a scénáře chyb.
Zátěž a latence: cíle SLO, testy p99/p999 latence, 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: QPS, chybovost, latence, využití limitů; alerty na SLO porušení.
API brány a registry: autentizace, limity, transformace, routing verzí, publikace do katalogu.
Rollback a canary: postupné nasazení, feature flagy, kompatibilita schémat při migracích DB.

Antipatterny a časté chyby

RPC převlečené za REST: endpointy typu /doAction bez zdrojů a bez sémantiky HTTP.
„Chattiness“: příliš mnoho drobných dotazů; řešte embedding a expand parametry (?include=items,customer), případně batch endpointy.
Nedeterministické chyby: inkonzistentní status kódy, nejednotný formát chyb.
Přetěžování GET: mění stav na GET (porušení bezpečnosti metody) a absence cache hlaviček.

REST vs. GraphQL vs. gRPC: kdy co zvolit

REST: jednoduchý, cacheovatelný, skvělé 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 resolvérů.
gRPC: binární Protobuf, plně duplexy, 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 jako „tunel“ přes HTTP.
Úroveň 1: zdroje.
Úroveň 2: správné metody a kódy.
Úroveň 3: hypermedia ovládá stav (HATEOAS).

Praktický návrhový checklist

Identifikujte doménové zdroje a jejich vztahy; navrhněte stabilní URI.
Ujistěte se, že metody a kódy odpovědí odpovídají sémantice.
Zaveďte jednotný chybový formát a korelační ID.
Specifikujte kontrakt (OpenAPI) a automatizujte validace.
Implementujte bezpečnost (OAuth/OIDC, TLS), rate limiting a audit.
Optimalizujte přenos (projekce, komprese, cache, ETagy).
Zajistěte stránkování, filtry a třídění s konzistentní syntaxí.
Nastavte observabilitu, SLO a release strategii (canary/rollback).
Plánujte evoluci: 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í DX (OpenAPI, automatizace, portál) lze stavět rozšiřitelná a dlouhodobě udržitelná rozhraní – ať už pro veřejné integrace, interní mikroservisy nebo mobilní a webové klienty.