API (Application Programming Interface): funkce a komunikace mezi systémy

API a integrace
P. Varga
API (Application Programming Interface): Funkce a komunikace mezi systémy

Co je API a proč na něm záleží

API (Application Programming Interface) je jednoznačně definované rozhraní, které umožňuje aplikacím a službám komunikovat a vyměňovat si data či funkce. API abstrahuje interní implementaci systému a poskytuje spotřebitelům stabilní smlouvu (contract). Díky API lze systémy modulárně skládat, integrovat partnery, automatizovat procesy a škálovat podnikání bez pevné vazby na konkrétní technologii.

Architektura komunikace: požadavky, odpovědi a zprávy

  • Synchronní vzor (request/response): klient odešle požadavek a čeká na odpověď (HTTP(S), gRPC).
  • Asynchronní vzor (event-driven): systémy si vyměňují zprávy o událostech prostřednictvím front/brokeru (AMQP, Kafka, MQTT); odesílatel nečeká na okamžitou odpověď.
  • Hybridní přístup: synchronní API pro dotazování na stav a asynchronní webhooky pro doručování událostí.

Hlavní styly API: REST, RPC, SOAP, GraphQL a gRPC

  • REST (Representational State Transfer): zdrojově orientovaný přístup nad HTTP, který využívá metody GET, POST, PUT, PATCH, DELETE a identifikátory zdrojů (URI). Data se nejčastěji vyměňují ve formátu JSON.
  • RPC (Remote Procedure Call): volání vzdálených procedur (např. JSON-RPC). Koncové body odpovídají operacím, nikoli zdrojům.
  • SOAP: protokol založený na XML s přísnou smlouvou (WSDL), rozšířeními (WS-*) a silnou podporou transakcí a zabezpečení v korporátní sféře.
  • GraphQL: dotazovací jazyk, v němž klient přesně specifikuje, jaká data požaduje (řeší přenos „příliš mnoho/příliš málo“); používá jeden koncový bod.
  • gRPC: binární komunikace nad HTTP/2 s protokolem Protocol Buffers; nabízí vysoký výkon, streamování a striktní typizaci.

Model zdrojů a návrh REST API

  • Identifikace zdrojů: URI by měla obsahovat podstatná jména reprezentující entity (/v1/objednavky/12345/polozky).
  • Metody: GET pro čtení, POST pro vytvoření/akci, PUT pro nahrazení, PATCH pro částečnou změnu, DELETE pro smazání.
  • Stavové kódy: používejte standardní kódy (200, 201, 202, 204, 400, 401, 403, 404, 409, 422, 429, 5xx) a konzistentní těla odpovědí.
  • HATEOAS (volitelné): odkazy v odpovědích (_links) usnadňují navigaci.
  • Idempotence: PUT a DELETE by měly být idempotentní; u POST použijte pro bezpečné opakování idempotency key.

Formáty dat a kontrakty

  • JSON: de facto standard pro webová API; jednoduchý a čitelný.
  • XML: bohatá schémata a jmenné prostory; tradičně se používá v SOAP.
  • Protocol Buffers / Avro: binární a efektivní serializace (gRPC, streamování, big data).
  • OpenAPI/Swagger: strojově čitelné specifikace HTTP API; umožňují generování dokumentace, validaci a tvorbu klientských SDK.
  • JSON Schema: formální popis struktury datových payloadů JSON; základ pro validaci a kontraktové testy.

Verzování API a kompatibilita

  • Verze v URL: /v1/… – jednoduché a přehledné řešení.
  • Verze v hlavičce: Accept: application/vnd.example.v2+json – lépe odděluje kontrakt od adresy.
  • Kompatibilita: změny přidávají pole, nikoli odstraňují; radikální změny vyžadují novou hlavní verzi.
  • Životní cyklus: oznámení o deprecation, období souběhu verzí a migrační průvodce.

Bezpečnost: autentizace, autorizace a přenos

  • TLS všude: šifrovaný přenos (HTTPS) je nezbytný.
  • OAuth 2.0 a OIDC: delegovaná autorizace, access tokeny a vrstva identity (OIDC) pro uživatelský kontext.
  • JWT: kompaktní nosič tvrzení; ověřujte podpis a dobu platnosti (exp, aud, iss) a rotujte klíče (JWKS).
  • API klíče: vhodné pro komunikaci server-server a méně citlivé scénáře; omezujte oprávnění a přístup podle IP adres.
  • Scopes a RBAC/ABAC: jemnozrnná oprávnění k operacím a zdrojům.
  • Ochrana proti útokům: omezení počtu požadavků, WAF, validace vstupů, ochrana proti opakovanému přehrání (nonce, idempotency key), zásady CORS.

Chybové modely a diagnostika

  • Konzistentní tělo chyby: pole code, message, details, traceId, případně fieldErrors pro validační chyby.
  • Mapování stavových kódů: 400 validační chyba, 401 chybějící/neplatná autentizace, 403 nedostatečná oprávnění, 404 neexistující zdroj, 409 konflikt, 422 sémantická chyba.
  • Možnost trasování: korelační identifikátory v hlavičkách (např. Trace-Id, Span-Id) pro distribuované trasování.

Výkonnost: cache, stránkování a filtrování

  • HTTP cache: hlavičky Cache-Control, ETag a If-None-Match pro podmíněné požadavky.
  • Stránkování: offset/limit nebo stránkování založené na kurzoru (cursor-based, nextCursor) pro rozsáhlé kolekce.
  • Filtrování a řazení: konzistentní parametry (?filter=status:active&sort=-createdAt), seznam povolených polí.
  • Komprese a výběr polí: gzip/br, pole fields=… nebo projekce GraphQL.

Asynchronní integrace: události, fronty a webhooky

  • Event-driven: publikování doménových událostí (např. OrderCreated) do brokeru (Kafka, RabbitMQ) s nastavenou dobou uchovávání a zárukami doručení.
  • Webhooky: zpětné volání přes HTTP při události; zabezpečte je podepsanými payloady, opakováním s exponenciálním prodlužováním prodlev a idempotencí.
  • Vzor outbox/inbox: spolehlivý přenos mezi databází a brokerem (odolnost vůči výpadkům a duplicitám).

API Gateway a správa rozhraní

  • Gateway: centralizuje autentizaci, autorizaci, směrování, limity, ukončení TLS, transformace a observabilitu.
  • Service Mesh: síťová vrstva (sidecar) pro vzory mTLS, opakování požadavků, přerušovač obvodů, omezení počtu požadavků a telemetrii uvnitř mikroslužeb.
  • Governance: katalog API, schvalování změn kontraktů, verzování a řízení životního cyklu, SLA/SLO.

Testování a kvalita: od kontraktu po provoz

  • Contract-first: definujte OpenAPI/Proto před implementací; generujte kostry kódu/SDK.
  • Automatické testy: jednotkové, integrační, kontraktové (spotřebitel ↔ producent), end-to-end, výkonnostní a zátěžové testy.
  • Mocky a simulace: urychlují vývoj klientů i serverů; umožňují deterministické scénáře.
  • CI/CD: kontrola kvality specifikace, generování klientů, bezpečnostní skenování závislostí a obrazů, nasazování typu canary.

Monitorování, logování a observabilita

  • Metriky: latence (p95/p99), chybovost, propustnost, vytížení zdrojů, počet odpovědí 4xx/5xx a 429 (omezení počtu požadavků).
  • Logy: strukturované (JSON) s korelačními ID; maskování osobních údajů (PII) a tajných údajů.
  • Trasování: distribuované tracing (OpenTelemetry); analýza závislostí a kořenových příčin.
  • Upozorňování: SLO/SLA, detekce regresí a zhoršení výkonu, provozní postupy pro zásahy.

Bezpečnost dat a compliance

  • Princip minimálních oprávnění: omezení tokenů a scopes, segmentace sítí a izolace tenantů.
  • Validace a sanitace: validace na straně serveru podle schématu, ochrana proti injekcím, omezení velikosti payloadu.
  • Šifrování: v klidu (disk, databáze) i při přenosu (TLS), správa klíčů (KMS, rotace, audit).
  • Audit a regulace: záznamy o přístupech, data retention, práva subjektů údajů (výmaz/oprava) a geografická omezení.

Praktické návrhové vzory

  • Částečná aktualizace: PATCH s JSON Merge/Patch; jasně definujte pravidla řešení konfliktů.
  • Hromadné operace: dávkové koncové body s částečně úspěšným zpracováním (partial success) a agregovanými chybami.
  • Transakce napříč službami: Saga pattern s kompenzačními kroky namísto dvoufázového commitu.
  • Stavové automaty: explicitní stavová pole a přechody; validace povolených změn.
  • Mezivrstvy: mapování DTO, vrstva anti-corruption při integraci se staršími systémy.

Uživatelská zkušenost vývojářů: dokumentace, SDK a příklady

  • Dokumentace: příklady požadavků/odpovědí, scénáře použití, přehled chyb, limity a zásady.
  • Klientská SDK: generujte je z kontraktu (OpenAPI/Proto); jejich verze synchronizujte s API.
  • Playground: interaktivní konzole (Swagger UI, GraphiQL) a testovací prostředí se sandboxovými daty.
  • Onboarding: registrace aplikací, správa klíčů, rotace tajných údajů a postupy pro řešení incidentů.

Výběr stylu API podle potřeby

  • REST/HTTP+JSON: interoperabilita, jednoduchost, veřejná i partnerská API.
  • GraphQL: flexibilní dotazy klientů (mobilní aplikace/SPA), snížení počtu opakovaných požadavků.
  • gRPC: vysoce výkonné interní mikroslužby, streamování, pevně definovaná schémata.
  • SOAP: regulovaná odvětví a starší systémy s požadavky na formální kontrakty.
  • Event-driven: volná vazba, integrace s mnoha spotřebiteli, vysoká škálovatelnost.

Typické problémy a jak jim předcházet

  • Dotazy N+1: slučujte koncové body, použijte includes/rozšíření nebo spojení (joins) v GraphQL.
  • Zpětně nekompatibilní změny: contract-first a kontrola schémat; semver a migrační období.
  • Nadměrná latence: cache, komprese, regiony blízko sebe, sdílení připojení (connection pooling), HTTP/2.
  • Duplicitní zprávy: idempotence; doručení exactly-once je nerealistické – navrhujte doručení at-least-once s deduplikací.
  • Nejasné chyby: jednotný model chyb, korelační ID a kvalitní dokumentace.

Závěr

API je kontrakt, který umožňuje systémům bezpečně a předvídatelně spolupracovat. Správný výběr stylu (REST, gRPC, GraphQL, SOAP), důsledné zabezpečení, kvalitní dokumentace, testování kontraktů a observabilita jsou základem úspěšné integrace. Kombinací synchronních požadavků a asynchronních událostí lze vybudovat odolnou a škálovatelnou integrační platformu, která dlouhodobě podporuje rozvoj i podnikání.