REST API a serverová logika

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, 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 (nahrazuje celou reprezentaci); 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 prohlídku 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
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í hlavičkami Accept a Content-Type (content negotiation). JSON je de facto standard (application/json). Verzi je vhodné řešit jako evoluční kontrakt (přidáváním kompatibilních polí), případně pomocí semver aliasů v URL (/v1/) nebo mediálních typů (application/vnd.example.v2+json).

Idempotence, bezpečnost metod a opakovatelnost

Pro spolehlivost a retrié klienty je klíčová idempotence. PUT a DELETE by měly být idempotentní, zatímco POST lze učinit idempotentním pomocí 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 značí 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 snížení objemu dat.

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: max-age, stale-while-revalidate, public/private.
Deterministické GET odpovědi umožňují efektivní využití CDN a proxy cache.

Hypermedia a HATEOAS

Hypermedia (odkazy v tělech odpovědí) pomáhají klientům objevovat dostupné akce a minimalizují potřebu hardcodovaných 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, s krátkou životností, rotací a omezením scope).
JWT: podepsané tokeny s claimy; je nutné dbát na expiraci a možnost revokace; nikdy neukládat citlivá data v otevřeném textu.
mTLS/klíče API: pro server-to-server a interní integrace; omezujte IP adresy, provádějte rotaci a auditing.
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ě; vracejte 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 také CSRF ochranu u přístupů založených na cookies.

Serverová logika: vrstvy a odpovědnosti

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

Doménový návrh a invariants

Serverová logika musí prosazovat invarianty (např. stav objednávky nesmí přeskočit kroky) a správně definovat transakční hranice. DDD (Domain-Driven Design) pomáhá s modelováním agregátů, entit, value objektů a doménových událostí.

Transakce, konkurence a konzistence

ACID transakce v relačních databázích, úroveň 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 časově náročné nebo nespolehlivé v synchronním HTTP. Používejte fronty a streamy (např. message brokery), outbox pattern, event-driven architektury a webhooky nebo polling endpointy (202 Accepted + Location s odkazem na stav úlohy), aby klient nemusel čekat na dokončení operace.

Výkon a škálování

Horizontální škálování: stateless servery za load balancerem, session ukládejte do sdíleného úložiště.
N+1 dotazy: eliminujte pomocí parametrů include, joinů, batch endpointů nebo 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: neduplikujte citlivá data v logech, 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, velikost odpovědí.
Distributed tracing: standardní kontext (např. W3C Trace Context), span kolem volání databáze 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 s plány deprecation.

Testování a kvalita

Testy kontraktu (consumer-driven) pro predikci nekompatibilit.
Jednotkové testy pro doménovou logiku, integrační pro DB a messaging, end-to-end pro klíčové workflow.
Chaos a DR testy: testování síťových výpadků, timeoutů, degradace downstream služeb a obnovy po selhání.

Distribuované vzory a architektura

Gateway (API Gateway) pro cross-cutting aspekty (auth, rate limiting, transformace, agregace).
Backend for Frontend (BFF) pro specifické potřeby UI a mobilních klientů.
Circuit breaker, bulkheads, timeouty, retries s exponential backoff a jitter.

Dokumentace a developer experience

Specifikace OpenAPI (YAML/JSON) je středem gravitačního pole: generuje klienty, serverové skeletony, testy a dokumentaci. Udržujte příklady požadavků/odpovědí, SDK, rychlé starty a Postman kolekce. Verzujte kontrakt a publikujte deprecation timeline.

Konvence pojmenování a konzistence

URI v kebab-case nebo snake_case, konzistentně (/user-profiles vs. /user_profiles).
Pole JSON v snake_case nebo camelCase podle klientských jazyků, hlavně konzistentně.
Č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 zabraňte duplicitám: klient přidá Idempotency-Key, server si jej uloží spolu s výsledkem a při opakování vrací stejnou odpověď. Klíč má omezenou platnost 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 krokování (přidat sloupec, nasadit kód, odstranit starý), migrační nástroje.
Feature flagy pro postupné odemyká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 auditní záznamy do bezpečného úložiště.