REST API a serverová logika: principy návrhu a fungování

REST jako architektonický styl a role serverové logiky

REST (REpresentational State Transfer) je architektonický styl pro návrh webových API, který vychází z principů webu a protokolu HTTP. REST neřeší pouze „jaké endpointy“ API obsahuje, ale především jak se pracuje se zdroji (resources), jejich reprezentacemi, stavem klienta a odpověďmi serveru. Serverová logika pak zajišťuje doménová pravidla, transakce, integrace s perzistencí a dalšími službami, bezpečnost, observabilitu a škálování.

Resource-orientovaný model: co je „zdroj“

Zdrojem (resource) je identifikovatelný objekt nebo kolekce v doméně (např. objednávka, uživatel, platba). Každý zdroj má URI (např. /orders/123) a může mít více reprezentací (JSON, XML). Kolekce jsou obvykle v množném čísle (/orders), konkrétní položka v jednotném čísle s identifikátorem (/orders/123).

HTTP metody a jejich sémantika

GET: načtení reprezentace zdroje; bez vedlejších efektů (safe), idempotentní.
POST: vytvoření zdroje v kolekci nebo spuštění serverové akce; ne-idempotentní.
PUT: plná aktualizace (nahrazení celé reprezentace); idempotentní.
PATCH: částečná aktualizace; nemusí být idempotentní, ale doporučuje se idempotentní návrh.
DELETE: odstranění zdroje; idempotentní (opakované volání vrací stejný stav).
HEAD/OPTIONS: metainformace a povolené metody, užitečné pro CORS a průzkum API.

HTTP status kódy a konzistentní kontrakty

Kategorie	Příklady	Typické použití
2xx Úspěch	200 OK, 201 Created, 204 No Content	Načtení, vytvoření (s `Location`), smazání/aktualizace bez těla odpovědi
3xx Přesměrování	304 Not Modified	Kešování s ETag
4xx Chyba klienta	400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity	Validace, autorizace, konflikty verzí
5xx Chyba serveru	500 Internal Server Error, 503 Service Unavailable	Neočekávané chyby, degradace služby

Reprezentace zdrojů, obsah a verze

Reprezentace se volí pomocí hlaviček Accept a Content-Type (content negotiation). JSON je de facto standard (application/json). Verze doporučujeme řešit jako evoluční kontrakt (přidáváním polí zpětně kompatibilně), případně pomocí semver aliasů v URI (/v1/) nebo mediálních typů (application/vnd.example.v2+json).

Idempotence, bezpečnost metod a opakovatelnost

Pro spolehlivost a retriable klienty je klíčová idempotence. PUT a DELETE by měly být idempotentní, POST lze zpravidla činit idempotentním přes idempotency keys (např. hlavička Idempotency-Key) zejména u platebních operací.

Filtrace, řazení, stránkování a projekce

Filtrace: dotazové parametry (?status=paid&from=2025-10-01).
Řazení: ?sort=-created_at,price (mínus pro sestupné pořadí).
Stránkování: offset/limit (?page=2&per_page=50) nebo cursor-based (?cursor=abc) pro robustní stránkování.
Projekce: výběr polí (?fields=id,name,total) pro menší objem dat v odpovědi.

Kešování: Cache-Control, ETag a podmíněné dotazy

Správné kešování zlepšuje latenci i náklady:

ETag a Last-Modified s If-None-Match/If-Modified-Since → 304 Not Modified.
Cache-Control: direktivy max-age, stale-while-revalidate, public/private.
Deterministické odpovědi GET usnadňují využití CDN a proxy cache.

Hypermedia a HATEOAS

Hypermedia (odkazy v tělech odpovědí) pomáhají klientům objevovat akce a minimalizují hardcodované URI. Příklady: _links.self.href, _links.next.href, akce nad stavem objednávky (cancel, refund), které server nabídne pouze tehdy, když to doménová pravidla dovolují.

Autentizace a autorizace

OAuth 2.0/OIDC: delegovaná identita a přístupové tokeny (bearer, krátká životnost, rotace, scope).
JWT: podepsané tokeny s claimy; dávat pozor na expiraci a revokaci; nikdy neukládat citlivá data v plaintextu.
mTLS/klíče API: pro server-to-server a interní integrace; omezovat IP, rotovat a auditovat.
Autorizace: RBAC/ABAC, policy-as-code (např. OPA) a princip nejmenších oprávnění.

Chybové modely a validace

Vracíme strojově čitelné chyby s kódem, zprávou, detailem a korelačním (trace) ID. Formát může vycházet z RFC 9457 Problem Details (type, title, status, detail, instance). Validace vstupů probíhá na hraně (controller) i v doméně; uvádějte pole, která selhala, a důvody.

CORS a bezpečný přístup z prohlížeče

Pro veřejná API je nutné správně nastavit CORS (hlavičky Access-Control-Allow-Origin, Methods, Headers, Credentials) a rozlišovat mezi simple a preflight požadavky. Zvažte CSRF ochranu pro přístupy založené na cookie.

Serverová logika: vrstvy a odpovědnosti

Routing: mapování URI a metody na kontrolerové akce, validace parametrů a schémat (JSON Schema).
Controller: orchestrace požadavku, převod DTO ⇆ doména, předání požadavku do servisní vrstvy.
Service (doménová logika): pravidla, konzistence, transakce, business procesy.
Repository/DAO: přístup k datům (SQL/NoSQL), agregace, mapování entit.
Integrace: volání dalších služeb (HTTP, gRPC, messaging), circuit breaker, retry, timeouty.

Doménový návrh a invarianty

Serverová logika musí prosazovat invarianty (např. stav objednávky nesmí přeskočit kroky) a transakční hranice. DDD (Domain-Driven Design) pomáhá modelovat agregáty, entity, value objekty a doménové události.

Transakce, konkurence a konzistence

ACID transakce v relačních databázích, izolace (READ COMMITTED, REPEATABLE READ, SERIALIZABLE).
Optimistické zámky (verzovací pole, If-Match + ETag) a řešení konfliktů (409 Conflict).
Ságy a kompenzační kroky v distribuovaných procesech místo globálních 2PC.

Asynchronní zpracování a messaging

Některé operace jsou dlouhotrvající nebo nespolehlivé na synchronní HTTP. Používejte fronty/streamy (např. „message broker“), outbox pattern, event-driven architektury a webhooky nebo polling endpointy (202 Accepted + Location na stav úlohy), aby klient nemusel čekat na dokončení.

Výkon a škálování

Horizontální škálování: stateless servery za load balancerem, session do sdíleného úložiště.
N+1 dotazy: eliminace pomocí include parametrů, joinů, batch endpointů, read-modelů.
Kešování: aplikace (hot path), CDN, databázová cache, stale-while-revalidate.
Profilace: měření latence na úrovni komponent, cold starty, optimalizace (pooly spojení, HTTP/2/3).

Bezpečnostní osvědčené postupy

Princip nejmenších oprávnění, rotace tajemství, oddělené prostředí, MFA pro správu.
Input sanitization, limitace velikosti payloadů, rate limiting, WAF.
Šifrování v přenosu (TLS) i v klidu, správná správa certifikátů a klíčů (KMS/HSM).
Audit a forenzní stopa: neukládejte citlivá data v logech duplicitně, používejte pseudonymizaci.

Observabilita: logy, metriky a tracing

Strukturované logy: korelační/trace ID v kontextu požadavku, úroveň závažnosti, maskování PII.
Metriky: latence p50/p95/p99, chybovost, průtok, saturace, velikosti odpovědí.
Distributed tracing: standardní kontext (např. W3C Trace Context), span kolem volání DB a downstream služeb.

Verzování a správa změn kontraktu

Upřednostňujte zpětně kompatibilní změny (přidání volitelných polí). Breaking změny seskupujte do větších milníků (/v2). Dokumentaci generujte z kontraktů (OpenAPI) a publikujte changelogy a plány postupného vyřazení (deprecation).

Testování a kvalita

Testy kontraktu (consumer-driven), aby se předešlo nekompatibilitám.
Jednotkové testy pro doménu, integrační pro databázi a messaging, end-to-end pro klíčové toky.
Chaos a DR testy: simulace výpadků sítě, timeouts, degradace downstream služeb, obnova po selhání.

Distribuované vzory a architektura

Gateway (API Gateway) pro cross-cutting funkce (autentizace, rate limiting, transformace, agregace).
Backend for Frontend (BFF) pro specifické potřeby UI a mobilních klientů.
Circuit breaker, bulkheads, timeouts, retries se exponenciální zpětnou vazbou a jitterem.

Dokumentace a developer experience

Specifikace OpenAPI (YAML/JSON) je středobodem: generuje klientské knihovny, serverové skeletony, testy a dokumentaci. Udržujte příklady požadavků a odpovědí, SDK, rychlé starty a Postman kolekce. Verzujte kontrakt a publikujte harmonogram vyřazení funkcí.

Konvence pojmenování a konzistence

URI v kebab-case nebo snake_case, konzistentně (/user-profiles vs. /user_profiles).
JSON pole v snake_case nebo camelCase dle jazyka klientů, důležitá je hlavně konzistence.
Čas v UTC ISO 8601, měny jako minor units (např. amount=1099 a currency=EUR).

Idempotency keys a bezpečné účtování

U plateb a objednávek zabráníte duplicitám: klient přidá Idempotency-Key, server ho uloží s výsledkem a při opakování volání vrací stejnou odpověď. Klíč časově expiruje a je vázán na konkrétní endpoint a hash payloadu.

Nasazení, verzování databáze a migrace

Blue/Green a Canary nasazení, rollback strategie.
Migrace schématu: expand–contract postup (přidat sloupec, nasadit kód, odstranit starý), používání migračních nástrojů.
Feature flagy pro postupné zpřístupňování funkcí.

Audit, compliance a životní cyklus dat

Logujte změny stavů a vlastníka akcí (kdo/kdy/co). Definujte retenční politiky, mazání dle regulací (např. GDPR), pseudonymizaci a šifrování polí. Exportujte