Návrh bezpečného REST API

Efektivní a bezpečné REST API

REST API je rozhraní pro výměnu dat a řízení procesů na principu zdrojů, nad kterými se provádějí standardní operace. Cílem dobře navrženého API je být predikovatelné, konzistentní, výkonné a především bezpečné. Tento článek pokrývá návrhové vzory, bezpečnostní postupy, standardy a provozní aspekty, které vedou k efektivním a odolným REST službám.

Doménový model a identifikace zdrojů

• Zdroj vs. reprezentace: zdroj je doménový objekt; reprezentace je serializace (např. JSON). Stabilní URI identifikují zdroje, nikoli akce.
• Granularita: navrhujte zdroje tak, aby odpovídaly přirozeným entitám a vztahům (např. /uzivatele, /objednavky, /uzivatele/{id}/objednavky).
• Názvosloví v množném čísle: zlepšuje konzistenci a čitelnost (např. /produkty místo /produkt).
• Adresovatelné podzdroje: hierarchie pro vazby 1:N a N:M; pro volné asociace použijte dotazy a filtry.

URI konvence, metody a sémantika

• HTTP metody: GET (read), POST (create, ne-idempotentní), PUT (replace, idempotentní), PATCH (partial update), DELETE (remove), HEAD (metadata), OPTIONS (capabilities).
• Bez sloves v cestě: preferujte POST /objednavky před /vytvorObjednavku; akce reprezentujte jako zdroje nebo kontrolované operace (např. /platby/{id}/refundace).
• Bezpečnost a idempotence: používejte metody dle sémantiky; PUT/DELETE mají být idempotentní, GET bez vedlejších efektů.

Verzování a kompatibilita

• Stabilita API je závazek: minimalizujte breaking změny; preferujte přidávání nových polí před přejmenováním či změnou významu.
• Strategie verzování: URI v1/v2, nebo mediální typy v hlavičkách (Accept: application/vnd.example.v2+json). Zvolte jednu strategii a dokumentujte její pravidla.
• Deprekační cyklus: oznamte datum ukončení, poskytujte varovné hlavičky (Deprecation, Sunset) a migrační průvodce.

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

• Predikovatelné parametry: ?page, ?limit, ?sort=field,-field2, ?filter[field]=value.
• Cursor-based pagination: škálovatelnější než offset; vracejte next/prev kurzory v links.
• Projekce a rozšíření: ?fields=a,b,c pro výběr polí, ?include=relace pro načtení souvisejících zdrojů.

Formát odpovědí a kontrakt

• Konzistentní obálka: sjednoťte strukturu odpovědí (data, metadata, page info, odkazy). Vracejte Content-Type a případně ETag.
• Standardizované chyby: používejte status, code, message, fields/details, korelační traceId. Vhodné je RFC 7807 (application/problem+json).
• Mezinárodní prostředí: zvažte lokalizovatelné zprávy a stabilní programátorské kódy chyb.

HTTP kódy a hlavičky

• 2xx: 200 OK, 201 Created s Location, 204 No Content po DELETE/PUT bez těla.
• 3xx: 304 Not Modified při validaci cache, 303 See Other po akci k asynchronnímu zdroji.
• 4xx: 400 validace, 401 autentizace, 403 autorizace, 404 neexistující zdroj, 409 konflikty, 422 nevalidní data, 429 rate limit.
• 5xx: serverové chyby; u asynchronních operací preferujte 202 Accepted a stavový zdroj.
• Cache hlavičky: ETag, Last-Modified, Cache-Control, Vary; pro bezpečnost také Strict-Transport-Security, X-Content-Type-Options, Content-Security-Policy pro web klienty.

Bezpečnostní základy: autentizace a autorizace

• TLS všude: vynucení HTTPS, ochrana před downgrade a správná konfigurace šifer.
• OAuth 2.1 a OIDC: pro delegovanou autentizaci; preferujte Authorization Code s PKCE. Pro server-to-server využijte client credentials.
• Tokeny: krátká životnost, rotace refresh tokenů, audience a scopy. Zvažte formát JWT s podepsáním a možností revokace přes introspekci.
• Autorizace: RBAC/ABAC, jemnozrnná práva na úrovni zdrojů; přenášejte minimální nutné scopy.

Ochrana proti běžným útokům

• Rate limiting a throttling: chrání před DoS a zneužitím; komunikujte limity v hlavičkách X-RateLimit-* a návrat 429.
• Input validation a normalizace: validujte délky, typy, formáty; odmítejte neznámá pole; používejte whitelist přístup.
• Output encoding: vyhněte se injekcím v klientech; správně nastavujte typy obsahu a kódování.
• Idempotence a replay ochrana: idempotency klíče pro platby a objednávky (Idempotency-Key), nonce a časové značky.
• Bezpečné logování: logujte minimální nutná data, maskujte PII/sekrety, nikdy neukládejte celé tokeny.

Integrita dat a souběh

• Optimistická konkurence: ETag s If-Match/If-None-Match pro bezpečné aktualizace a prevenci ztráty dat.
• Transakční hranice: konsistentní chování při částečných selháních; u více-krokových operací návrh kompenzací (saga).
• Idempotentní návrh: opakované požadavky nesmí způsobit duplicitní efekty.

Výkon a škálování

• HTTP cache: využijte cacheable GET s ETag; respektujte Cache-Control a Vary.
• Agregace a selektivní načítání: projekce polí, zahrnutí vztahů, ale opatrně s „overfetchingem“.
• Komprese a velikost payloadu: povolte gzip/br, limitujte maximální velikosti požadavků a odpovědí.
• Asynchronní zpracování: u operací s dlouhým během použijte 202 Accepted a stavové zdroje nebo webhooky.
• Horizontální škálování: bezstavové servery, sticky-less load balancing, sdílení stavu přes úložiště či fronty.

Observabilita, měření a spolehlivost

• Strukturované logy: korelační traceId/spanId, standardizované klíče, JSON logy.
• Tracing a metriky: APM, distribuované trasování, metriky latence, sazby chyb a saturace; RED/USE metodiky.
• SLA/SLO: definujte cílové latence a dostupnost; měřte chybovost per endpoint a per tenant.
• Circuit breaker a retry: exponenciální backoff, jitter, limity pokusů; idempotence požadavků.

Dokumentace a kontrakty

• OpenAPI specifikace: jediný zdroj pravdy pro schémata, validaci a generování klientů a testů.
• Konzistentní příklady: uvádějte vzorové požadavky/odpovědi, chybové stavy a hraniční případy.
• Changelog: udržujte historii změn, deprekační poznámky a migrační instrukce.

Testování a kvalita

• Validace schémat: kontraktové testy proti OpenAPI, statická i runtime validace payloadu.
• Jednotkové a integrační testy: pokrývají logiku, autorizaci, chybové větve, limity a výkon.
• Bezpečnostní testy: negativní scénáře, fuzzing, skeny OWASP API Top 10, kontrola misconfigurací CORS a hlaviček.
• Test data management: deterministická data, anonymizace PII a izolace multi-tenant scénářů.

Správa verzí klientů a SDK

• Generované SDK: udržujte pro hlavní jazyky; verze SDK mapujte na verze API, dodávejte migrační gajdy.
• Backwards compatibility v klientech: tolerujte nová neznámá pole; neusuzujte na úplnost dat.

Řízení chyb a odolnost vůči selháním

• Predikovatelné chybové formáty: klient musí být schopen automaticky reagovat; vracejte stabilní kódy a detailní errors[].field.
• Omezení informací: u 4xx/5xx nesdělujte interní implementační detaily; logujte je pouze na serveru.
• Graceful degradation: Feature flags, fallbacky a read-only režimy při částečných výpadcích.

Správa dat, ochrana soukromí a compliance

• PII a citlivá data: minimalizace sběru, šifrování za letu i v klidu, řízení přístupu a audit.
• Retention a práva subjektů: endpointy a procesy pro mazání/anonimizaci dle regulací (např. „right to be forgotten“).
• Multitenancy: striktní oddělení dat tenantů na úrovni autorizace i dotazů; testujte „tenant escape“ scénáře.

CORS a bezpečná integrace s webovými klienty

• Princip minimální nutnosti: povolte jen nezbytné originy, metody a hlavičky; nikdy nepovolujte * pro Authorization.
• Credentials: používejte pouze tam, kde je to nutné; zvažte tokeny v Authorization místo cookies.

Provozní model a CI/CD

• Automatizované nasazení: validace schémat, bezpečnostní skeny a smoke testy v pipeline.
• Konfigurovatelnost: konfigurace přes proměnné prostředí a tajemství spravujte v trezoru; žádná tajemství v repozitáři.
• Canary a postupný rollout: omezte dopad regresí, sbírejte telemetrii před plným nasazením.

Metodické vzory a anti-patterns

• Doporučené vzory: HATEOAS pro navigaci, resource expansion s limity, idempotency klíče, explicitní stavové stroje pro dlouhé procesy.
• Anti-patterns: přetížené POST endpointy pro libovolné akce, nekonzistentní názvosloví, skryté breaking změny, přenos nadbytečných dat, unikající interní chybové stacky.

Ukazatele úspěchu (KPI) pro REST API

Best practices – shrnutí

1. Modelujte zdroje podle domény a používejte konzistentní URI a metody.
2. Definujte a dodržujte kontrakt pomocí OpenAPI, s verzováním a jasnou deprecací.
3. Vynucujte bezpečnost: TLS, OAuth/OIDC, minimální scopy, rate limiting, validaci a audit.
4. Optimalizujte výkon: cache, kompresi, stránkování a asynchronní zpracování.
5. Zaveďte observabilitu, strukturované logy a SLO; automatizujte CI/CD a bezpečnostní kontroly.
6. Chyby navrhujte předvídatelně, bez úniku interních detailů; dbejte na idempotenci.
7. Respektujte soukromí a compliance; testujte multi-tenant izolaci a „negativní“ scénáře.

Závěr

Efektivní a bezpečné REST API je výsledkem disciplinovaného návrhu, důsledné bezpečnostní hygieny a zralých provozních praktik. Dodržování standardů HTTP, sémantiky metod, konzistentních kontraktů a obranných vrstev proti zneužití umožní stavět rozhraní, která jsou dlouhodobě udržitelná, snadno integrovatelná a spolehlivá. Takové API se stává stabilním základem pro digitální produkty, mobilní aplikace i integrace mezi systémy.