REST API a serverová logika: fungování a návrh

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 má, 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, zabezpečení, observabilitu a škálování.

Model orientovaný na zdroje: 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 se obvykle pojmenovávají v množném čísle (/orders), konkrétní položka v jednotném čísle s identifikátorem (/orders/123).

Metody HTTP a jejich sémantika

• GET: načtení reprezentace zdroje; bez vedlejších účinků (safe), idempotentní.
• POST: vytvoření zdroje v kolekci nebo spuštění serverové akce; není idempotentní.
• PUT: úplná aktualizace (nahradí celou reprezentaci); idempotentní.
• PATCH: částečná aktualizace; nemusí být idempotentní, doporučuje se však navrhnout ji jako idempotentní.
• DELETE: odstranění zdroje; idempotentní (opakované volání vrací stejný výsledek z hlediska stavu).
• HEAD/OPTIONS: metadata a povolené metody, užitečné pro CORS a prozkoumávání API.

Stavové kódy HTTP a konzistentní kontrakty

Reprezentace zdrojů, obsah a verze

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

Idempotence, bezpečnost metod a opakovatelnost

Pro spolehlivost a klienty, kteří opakují požadavky, je klíčová idempotence. Metody PUT a DELETE by měly být idempotentní, POST lze učinit idempotentním pomocí idempotency keys (např. hlavičky Idempotency-Key) u platebních operací.

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

• Filtrování: parametry dotazu (?status=paid&from=2025-10-01).
• Řazení: ?sort=-created_at,price (minus označuje sestupné pořadí).
• Stránkování: offset/limit (?page=2&per_page=50) nebo stránkování založené na kurzoru (?cursor=abc) pro robustní stránkování.
• Projekce: výběr polí (?fields=id,name,total) pro menší payloady.

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

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

• ETag a Last-Modified spolu s If-None-Match/If-Modified-Since → 304 Not Modified.
• Cache-Control: 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í natvrdo zakódovaná 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á platnost, rotace, scope).
• JWT: podepsané tokeny s claimy; je třeba dát pozor na expiraci a odvolání; nikdy neukládat citlivá data v nešifrovaném textu.
• mTLS/klíče API: pro komunikaci mezi servery a interní integrace; omezovat IP adresy, klíče rotovat a vše auditovat.
• Autorizace: RBAC/ABAC, policy-as-code (např. OPA) a princip nejmenších oprávnění.

Modely chyb a validace

Vracíme strojově čitelné chyby s kódem, zprávou, podrobnostmi a korelačním identifikátorem (trace id). Formát může vycházet z RFC 9457 Problem Details (type, title, status, detail, instance). Vstupy se validují na hranici systému (controller) i v doméně; uvádějte pole, u kterých validace selhala, a důvody.

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

U veřejných API je nutné správně nastavit CORS (hlavičky Access-Control-Allow-Origin, Methods, Headers, Credentials) a rozlišovat mezi požadavky simple a preflight. U přístupů založených na cookies zvažte ochranu CSRF.

Serverová logika: vrstvy a odpovědnosti

• Routing: mapování URI a metody na akce kontrolerů, validace parametrů a schémat (JSON Schema).
• Controller: orchestruje zpracování požadavku, převádí DTO ⇆ doménové objekty a předává požadavek servisní vrstvě.
• Service (doménová logika): pravidla, konzistence, transakce, podnikové 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, opakování požadavků, časové limity.

Doménový návrh a invarianty

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

Transakce, souběžnost a konzistence

• ACID transakce v relačních databázích, úrovně 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 namísto globálního 2PC.

Asynchronní zpracování a messaging

Některé operace trvají dlouho nebo jsou při synchronním použití HTTP nespolehlivé. Používejte fronty/streamy (např. „message broker“), outbox pattern, architektury založené na událostech a webhooky nebo endpointy pro polling (202 Accepted + Location na stav úlohy), aby klient nemusel čekat na dokončení.

Výkon a škálování

• Horizontální škálování: bezstavové servery za load balancerem, relace ve sdíleném úložišti.
• Dotazy N+1: eliminace pomocí parametrů include, spojení, dávkových endpointů a čtecích modelů.
• Kešování: na úrovni aplikace (hot path), CDN, databázová cache, stale-while-revalidate.
• Profilování: měření latence na úrovni komponent, cold starty, optimalizace (pooly připojení, HTTP/2/3).

Osvědčené postupy v oblasti zabezpečení

• Princip nejmenších oprávnění, rotace tajných údajů, oddělená prostředí, MFA pro správu.
• Sanitizace vstupů, omezení velikosti payloadů, rate limiting, WAF.
• Šifrování při přenosu (TLS) i v klidovém stavu, správná správa certifikátů a klíčů (KMS/HSM).
• Audit a forenzní stopa: neukládat duplicitně citlivá data do logů, používat pseudonymizaci.

Observabilita: logy, metriky a tracing

• Strukturované logy: korelační ID/trace ID v kontextu požadavku, úrovně závažnosti, maskování PII.
• Metriky: latence p50/p95/p99, chybovost, propustnost, saturace, velikost odpovědí.
• Distribuované trasování: standardní kontext (např. W3C Trace Context), span kolem volání databáze a navazujících služeb.

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

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

Testování a kvalita

• Testy kontraktu (řízené konzumentem), které pomáhají předcházet nekompatibilitám.
• Jednotkové testy domény, integrační testy databáze a messagingu, end-to-end testy klíčových toků.
• Testy odolnosti vůči chaosu a obnovy po havárii: výpadky sítě, časové limity, degradace navazujících služeb, obnova po selhání.

Distribuované vzory a architektura

• Gateway (API Gateway) pro průřezové funkce (auth, rate limiting, transformace, agregace).
• Backend for Frontend (BFF) pro specifické potřeby uživatelských rozhraní a mobilních klientů.
• Circuit breaker, bulkheads, timeouts, retries s exponential backoff a jitter.

Dokumentace a zkušenost vývojářů

Specifikace OpenAPI (YAML/JSON) je gravitačním středem: generují se z ní klienti, kostry serverů, testy a dokumentace. Udržujte příklady požadavků a odpovědí, SDK, návody pro rychlý start a kolekce Postman. Verzujte kontrakt a zveřejňujte harmonogram deprecation.

Konvence pojmenování a konzistence

• URI zapisujte konzistentně ve formátu kebab-case nebo snake_case (/user-profiles vs. /user_profiles).
• Pole JSON zapisujte ve formátu snake_case nebo camelCase podle jazyků používaných klienty, především však konzistentně.
• Čas uvádějte 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 předcházejte duplicitám: klient přidá Idempotency-Key, server jej uloží spolu s výsledkem a při opakování vrátí stejnou odpověď. Klíč po určité době expiruje a je vázán na konkrétní endpoint a hash payloadu.

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

• Nasazení Blue/Green a Canary, strategie návratu k předchozí verzi.
• Migrace schématu: postupné kroky expand–contract (přidat sloupec, nasadit kód, odstranit starý sloupec), migrační nástroje.
• Feature flagy pro postupné zpřístupňování funkcí.

Audit, compliance a životní cyklus dat

Logujte změny stavů a vlastníky akcí (kdo/kdy/co). Definujte retenční politiky, mazání v souladu s regulacemi (např. GDPR), pseudonymizaci a šifrování polí. Exportujte auditní záznamy do bezpečného úložiště.

Příklady návrhových rozhodnutí

• POST /orders vytvoří objednávku; vrátí 201 Created + Location: /orders/{id} a tělo s objednávkou.
• GET /orders?status=pending&sort=-created_at vrátí stránkovanou kolekci s odkazy pro stránkování.
• PUT /orders/{id} nahradí celou objednávku (idempotentní), PATCH změní jen některá pole.
• DELETE /orders/{id} je idempotentní: poprvé 204, podruhé také 204 nebo 404 podle zvolené politiky.

Závěr: REST API jako stabilní kontrakt nad doménou

REST API je víc než soubor endpointů – je to kontrakt mezi klienty a serverem, který platí v čase. Dobře navržená serverová logika vynucuje doménová pravidla, chrání konzistenci a zajišťuje škálovatelný a bezpečný provoz. Konzistentní sémantika HTTP, správné stavové kódy, kešování, zabezpečení, observabilita, testy kontraktu a promyšlené verzování jsou klíčové pro API, která dokážou růst a přizpůsobovat se měnícím požadavkům bez bolestivých přepisů.