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

Telekomunikace
Veronika Benková
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 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), možnost ukládání do mezipaměti a ideálně hypermedia jako motor stavu aplikace (HATEOAS).

Návrh zaměřený na zdroje a URI

  • Podstatná jména, 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.
  • Filtrování a stránkování: parametry dotazu (např. ?status=paid&limit=50&offset=100).
  • Stabilita: URI by měly být trvalé; verzování řešte jinak než v názvu zdroje, viz sekce o verzování.

Metody HTTP a sémantika

  • GET: čtení zdrojů; bezpečná a idempotentní metoda.
  • POST: vytvoření nebo neidempotentní operace (spuštění workflow). Vytvořený zdroj vraťte se stavovým kódem 201 Created a hlavičkou Location.
  • PUT: úplná idempotentní aktualizace reprezentace zdroje.
  • PATCH: částečná aktualizace (např. JSON Patch); nemusí být idempotentní, ale její idempotence se doporučuje.
  • DELETE: odstranění zdroje; idempotentní metoda (opakované volání nesmí škodit).
  • HEAD/OPTIONS: metadata a vyjednání možností (CORS, Allow).

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

  • 2xx: 200 OK, 201 Created, 204 No Content.
  • 3xx: přesměrování (v API méně časté).
  • 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.

Formát chyb: sjednoťte schéma, např. { "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 vyjednávání obsahu prostřednictvím hlavičky Accept, případně alternativní reprezentace (CSV, iCal). Omezte „magické“ formáty v parametrech dotazu; formální vyjednávání je srozumitelnější a lépe podporuje ukládání do mezipaměti.

HATEOAS a hypermedia

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

Idempotence a bezpečnost operací

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

Mezipaměť, 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 odpovědí, které nelze ukládat do mezipaměti, používejte no-store (např. u osobních údajů).

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

  • Stránkování založené na kurzorech: zajišťuje větší stabilitu výsledků než offset/limit; vracejte kurzory next/prev.
  • Třídění a filtry: např. ?sort=-createdAt,price&status=paid.
  • Výběr polí (projekce): ?fields=id,status,total pro menší objem dat.

Autentizace, autorizace a bezpečnost

  • OAuth 2.1 / OIDC: pro delegovaná oprávnění a přístup třetích stran; používejte standardní toky (Authorization Code s PKCE).
  • Přístupové tokeny JWT: krátká doba platnosti, audience, issuer, rotace klíčů (JWKS). Pro dlouhé relace používejte raději refresh token mimo kontext prohlížeče.
  • Model rozsahů oprávnění a rolí: granulární oprávnění, autorizace založená na atributech (ABAC) pro scénáře RLS.
  • Přenos: vždy HTTPS, HSTS, bezpečné cookies (HttpOnly, Secure), ochrana proti CSRF při autentizaci založené na cookies.
  • Validace vstupů a limity: maximální velikost těla (max body size), validace podle schématu, ochrana proti injekci JSON.
  • Omezování rychlosti a škrcení provozu: standardizujte hlavičky (RateLimit-Limit, -Remaining, -Reset), exponenciální prodlevu mezi opakovanými pokusy, měkké i pevné kvóty.

CORS a integrace webového frontendu

Pro prohlížeče nastavte řízené CORS: Access-Control-Allow-Origin (u privátního API nepoužívejte *), Allow-Credentials podle potřeby a minimalizujte množinu metod a hlaviček v Access-Control-Allow-Methods/-Headers. Odpovědi na preflight požadavky ukládejte do mezipaměti (Access-Control-Max-Age).

Verzování a kompatibilita

  • Bezpečný vývoj: přidávání polí je obvykle zpětně kompatibilní; odstraňování polí nebo změna jejich významu představuje zásadní změnu.
  • Způsoby verzování: hlavička Accept: application/vnd.example.v2+json (vyjednávání obsahu), méně často /v1 v URI. Upřednostněte řízení prostřednictvím schématu kontraktu.
  • Zásady ukončování podpory: oznamte změny v hlavičkách (Deprecation, Sunset), poskytněte migrační příručku a sandbox.

Specifikace: OpenAPI/Swagger, JSON Schema

Formální kontrakt zvyšuje kvalitu i míru automatizace. OpenAPI definuje operace, schémata, zabezpečení a odpovědi; JSON Schema slouží k validaci. Z kontraktu generujte klientské SDK, serverové kostry, testy a dokumentaci. Udržujte kontrakt jako zdroj pravdy (přístup design-first nebo code-first s kvalitní synchronizací).

Dokumentace a DX (zkušenost vývojářů)

  • Referenční dokumentace: přehledně popsaná pole, příklady požadavků a odpovědí, chybové kódy.
  • Tutoriály a rychlé úvody: funkční ukázky v populárních jazycích, kolekce Postman, ukázky příkazů curl.
  • Portál a klíče: samoobslužná registrace, rotace klíčů, přehled limitů a využití.

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

  • Testování kontraktu: mezi konzumentem a poskytovatelem (Pact), aby změny nerozbily klienty.
  • Integrační testy: proti skutečnému běhovému prostředí (Testcontainers), včetně přípravy dat a chybových scénářů.
  • Zátěž a latence: cíle SLO, testy latence p99/p999, testy odolnosti vůči výpadkům.

Provoz, observabilita a správa

  • Logování a trasování: korelační ID, strukturované logy, distribuované trasování (W3C Trace Context).
  • Metriky: QPS, chybovost, latence, využití limitů; upozornění při porušení SLO.
  • API brány a registry: autentizace, limity, transformace, směrování verzí, publikování do katalogu.
  • Návrat k předchozí verzi a kanárkové nasazení: postupné nasazování, příznaky funkcí, kompatibilita schémat při migracích databáze.

Antivzory a časté chyby

  • RPC převlečené za REST: koncové body typu /doAction bez zdrojů a bez sémantiky HTTP.
  • Příliš mnoho drobných požadavků: příliš mnoho drobných dotazů; řešte vkládání souvisejících dat a parametry expand (?include=items,customer), případně dávkové koncové body.
  • Nedeterministické chyby: nekonzistentní stavové kódy, nejednotný formát chyb.
  • Zneužívání metody GET: změna stavu prostřednictvím GET (porušení bezpečnostních vlastností metody) a absence hlaviček pro ukládání do mezipaměti.

REST vs. GraphQL vs. gRPC: co a kdy zvolit

  • REST: jednoduchý, podporuje ukládání do mezipaměti a skvěle se hodí pro CDN; ideální pro veřejná API a integrační vrstvy.
  • GraphQL: flexibilní dotazování a projekce dat, méně drobných požadavků u komplexních klientů; vyšší nároky na zabezpečení a výkon resolverů.
  • gRPC: binární Protobuf, plně duplexní komunikace, nízká latence; vhodné pro mikroslužby a interní komunikaci, méně vhodné pro prohlížeče bez brány.

Model zralosti REST (Richardsonův model zralosti)

  1. Úroveň 0: jediné koncové body jako „tunel“ přes HTTP.
  2. Úroveň 1: zdroje.
  3. Úroveň 2: správné metody a kódy.
  4. Úroveň 3: hypermedia řídí stav (HATEOAS).

Praktický kontrolní seznam návrhu

  • Identifikujte doménové zdroje a jejich vztahy; navrhněte stabilní URI.
  • Ujistěte se, že metody a stavové kódy odpovědí odpovídají sémantice.
  • Zaveďte jednotný formát chyb a korelační ID.
  • Specifikujte kontrakt (OpenAPI) a automatizujte validace.
  • Implementujte zabezpečení (OAuth/OIDC, TLS), omezování rychlosti a audit.
  • Optimalizujte přenos (projekce, komprese, ukládání do mezipaměti, ETagy).
  • Zajistěte stránkování, filtry a třídění s konzistentní syntaxí.
  • Nastavte observabilitu, SLO a strategii vydávání (kanárkové nasazení/návrat k předchozí verzi).
  • Plánujte další vývoj: verzování, ukončování podpory, migrační příručky.

Závěr

API a služby REST tvoří páteř moderních digitálních ekosystémů. Úspěch stojí na pevných základech sémantiky HTTP, doménového návrhu, zabezpečení, vývoje řízeného kontraktem a provozní disciplíny. Kombinací osvědčených principů (návrh zaměřený na zdroje, idempotence, ukládání do mezipaměti) s kvalitní zkušeností vývojářů (OpenAPI, automatizace, portál) lze vytvářet rozšiřitelná a dlouhodobě udržitelná rozhraní – ať už pro veřejné integrace, interní mikroslužby nebo mobilní a webové klienty.