Technologie

Návrh bezpečného REST API rozhraní

Lucie Čermáková 0

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 (čtení), POST (vytvoření, ne-idempotentní), PUT (zaměnění, idempotentní), PATCH (částečná aktualizace), DELETE (odstranění), HEAD (metadata), OPTIONS (možnosti).
  • 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 podle jejich sémantiky; PUT a DELETE mají být idempotentní, GET bez vedlejších efektů.

Verzování a kompatibilita

  • Stabilita API je závazek: minimalizujte prolamující 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í, poskytněte 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 pageování: škálovatelnější než offset; vracejte next a 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, informace o stránkování, 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 nebo 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 překročení limitu.
  • 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 webové klienty.

Bezpečnostní základy: autentizace a autorizace

  • TLS všude: vynucování HTTPS, ochrana před downgrade útoky 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 podepisová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 vracejte 429.
  • Validace vstupů a normalizace: validujte délky, typy, formáty; odmítejte neznámá pole; používejte whitelist přístup.
  • Escapování výstupu: vyhněte se injekcím ve front-endu; správně nastavujte typy obsahu a kódování.
  • Idempotence a ochrana proti opakování: 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 osobní údaje a tajné informace, 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: konzistentní chování při částečných selháních; u vícekrokových operací navrhněte kompenzace (saga).
  • Idempotentní návrh: opakované požadavky nesmí způsobit duplicitní efekty.

Výkon a škálování

  • HTTP cache: využijte cacheovatelné 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 a br, limitujte maximální velikost 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é logování: korelační traceId/spanId, standardizované klíče, JSON logy.
  • Tracing a metriky: APM, distribuované trasování, metriky latence, míry chyb a saturace; metodiky RED a USE.
  • 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 a 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 konfigurace CORS a hlaviček.
  • Testovací data management: deterministická data, anonymizace osobních údajů 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í návody.
  • Zpětná kompatibilita v klientech: tolerujte nová neznámá pole; nevyvozujte závěry o úplnosti 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 flagy, fallbacky a read-only režimy při částečných výpadcích.

Správa dat, ochrana soukromí a compliance

  • Osobní a citlivá data: minimalizujte sběr, používejte šifrování při přenosu i uložení, řízení přístupu a audit.
  • Retenční politika a práva subjektů: endpointy a procesy pro mazání/anonimizaci dle regulací (např. „právo být zapomenut“).
  • Multitenancy: striktní oddělení dat tenantů na úrovni autorizace i dotazů; testujte scénáře „tenant escape“.

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 bezpečném úložišti; žá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-patterny

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

Ukazatele úspěchu (KPI) pro REST API

Lucie Čermáková

Website:

Related Story
Oblast Metoda Význam Cílový trend
Výkon P95/P99 latence, propustnost Uživatelská zkušenost, kapacita Snižovat / Zvyšovat
Spolehlivost Míra chyb 5xx/4xx, dostupnost Kvalita provozu Snižovat / Zvyšovat
Bezpečnost Počet incidentů, úspěšnost blokací Odolnost vůči útokům Snižovat / Zvyšovat
Použitelnost Čas integrace, počet dotazů na podporu Zkušenost vývojářů Snižovat