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ý staví na principech webu a protokolu HTTP. REST neřeší pouze „jaké endpointy“ API má, ale hlavně jak se pracuje se zdroji (resources), jejich reprezentacemi, stavem klienta a odpovědmi 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 postranních efektů (safe), idempotentní.
• POST: vytvoření zdroje v kolekci nebo spuštění serverové akce; ne-idempotentní.
• PUT: plná aktualizace (nahradí 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í tentýž výsledek stavu).
• 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). Verze se doporučuje řešit jako evoluční kontrakt (přidávat pole 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 činit idempotentním přes idempotency keys (např. hlavička Idempotency-Key) 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ě).
• 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ší payloady.

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 usnadňují 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 korelací (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, jež 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 cookie-based přístupy.

Serverová logika: vrstvy a odpovědnosti

• Routing: mapování URI + metody na kontrolerové akce, validace parametrů a schémat (JSON Schema).
• Controller: orchestrace požadavku, převod DTO ⇆ doména, požadavek předává 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 invariants

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 DB, 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 dlouhé 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 job stav), 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 přes include parametry, joiny, batch endpointy, read-modely.
• 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 transportu (TLS) i v klidu, správná správa certifikátů a klíčů (KMS/HSM).
• Audit a forenzní stopa: neduplikovat citlivá data v logách, pseudonymizace.

Observabilita: logy, metriky a tracing

• Strukturované logy: korelační/trace ID v kontextu požadavku, úroveň severities, 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 backward compatible 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 deprecation plány.

Testování a kvalita

• Testy kontraktu (consumer-driven), aby se předešlo nekompatibilitám.
• Jednotkové testy pro doménu, integrační pro DB a messaging, end-to-end pro klíčové toky.
• Chaos a DR testy: síťové výpadky, timeouts, degradace downstreamů, obnova po selhání.

Distribuované vzory a architektura

• Gateway (API Gateway) pro cross-cutting (auth, rate limiting, transformace, agregace).
• Backend for Frontend (BFF) pro specifické potřeby UI a mobilních klientů.
• Circuit breaker, bulkheads, timeouts, retries se 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 dle jazyka klientů, 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 ho persistuje s výsledkem a při opakování vrací stejnou odpověď. Klíč časově expiruje a je vázán na konkrétní endpoint a payload hash.

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ě.

Příklady návrhových rozhodnutí

• POST /orders vytváří objednávku; vrací 201 Created + Location: /orders/{id} a tělo s objednávkou.
• GET /orders?status=pending&sort=-created_at vrací stránkovanou kolekci se stránkovacími odkazy.
• PUT /orders/{id} nahrazuje celou objednávku (idempotentní), PATCH mě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ž sbírka endpointů – je to kontrakt mezi klienty a serverem v čase. Dobře navržená serverová logika prosazuje doménová pravidla, chrání konzistenci a udržuje škálovatelný a bezpečný provoz. Konzistentní sémantika HTTP, správné status kódy, kešování, bezpečnost, observabilita, testy kontraktu a promyšlené verzování jsou klíčové pro API, která vydrží růst a měnící se požadavky bez bolestivých přepisů.