Co je API

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 stabilní smlouvu (contract) pro spotřebitele. Díky API lze systémy modulárně skládat, integrovat partnery, automatizovat procesy a škálovat byznys 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 událostí přes fronty/broker (AMQP, Kafka, MQTT); odesílatel nečeká na okamžitou odpověď.
• Hybridní přístup: synchronní API pro dotazování stavu a asynchronní webhooky pro doručení událostí.

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

• REST (Representational State Transfer): zdrojově orientovaný přístup nad HTTP, využívá metody GET, POST, PUT, PATCH, DELETE a identifikátory zdrojů (URI). Výměna dat nejčastěji ve formátu JSON.
• RPC (Remote Procedure Call): volání vzdálených procedur (např. JSON-RPC). End-pointy odpovídají operacím, ne zdrojům.
• SOAP: protokol nad XML s přísnou smlouvou (WSDL), rozšířeními (WS-*) a silnou podporou transakcí a bezpečnosti v korporátní sféře.
• GraphQL: dotazovací jazyk; klient přesně specifikuje, jaká data chce (řeší přenos „příliš mnoho/málo“), jeden end-point.
• gRPC: binární komunikace nad HTTP/2 s protokolem Protocol Buffers; vysoký výkon, streaming a striktní typizace.

Model zdrojů a návrh REST API

• Identifikace zdrojů: URI by měla být podstatná jména reprezentující entity (/v1/objednavky/12345/polozky).
• Metody: GET pro čtení, POST pro vytvoření/akce, PUT pro nahrazení, PATCH pro parciální 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) usnadní navigaci.
• Idempotence: PUT a DELETE by měly být idempotentní; u POST pro bezpečné opakování použijte idempotency key.

Formáty dat a kontrakty

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

Verzování API a kompatibilita

• Verze v URL: /v1/… – jednoduché a čitelné.
• Verze v hlavičce: Accept: application/vnd.example.v2+json – lepší oddělení kontraktu od adresy.
• Kompatibilita: změny přidávají pole, neodstraňují; radikální změny vyžadují novou major verzi.
• Životní cyklus: deprecation oznámení, doba souběhu verzí, migrační průvodce.

Bezpečnost: autentizace, autorizace a transport

• TLS všude: šifrovaný transport (HTTPS) je nezbytný.
• OAuth 2.0 a OIDC: delegovaná autorizace, access tokeny a identitní vrstva (OIDC) pro uživatelské kontexty.
• JWT: kompaktní nosič tvrzení; validujte podpis a expiraci (exp, aud, iss), rotujte klíče (JWKS).
• API klíče: vhodné pro server-to-server a méně citlivé scénáře; omezujte práva a IP.
• Scopes a RBAC/ABAC: jemnozrnná práva k operacím a zdrojům.
• Ochrana proti útokům: rate limiting, WAF, validace vstupů, ochrana proti replay (nonce, idempotency key), CORS politika.

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í/špatná autentizace, 403 nedostatečná práva, 404 neexistující zdroj, 409 konflikt, 422 sémantická chyba.
• Traceability: 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é dotazy.
• Stránkování: offset/limit nebo cursor-based (nextCursor) pro velké kolekce.
• Filtrování a třídění: konzistentní parametry (?filter=status:active&sort=-createdAt), whitelist polí.
• Komprese a selektivní pole: gzip/br, pole fields=… nebo GraphQL projekce.

Asynchronní integrace: události, fronty a webhooky

• Event-driven: publikace doménových událostí (např. OrderCreated) do brokeru (Kafka, RabbitMQ) s retencí a doručovacími zárukami.
• Webhooky: zpětné HTTP volání při události; zabezpečte podepsanými payloady, opakováním s exponenciálním backoffem a idempotencí.
• Outbox/inbox pattern: spolehlivý přenos mezi DB a brokerem (odolnost vůči výpadkům a duplicitám).

API Gateway a správa rozhraní

• Gateway: centralizace autentizace, autorizace, routingu, limitů, TLS terminace, transformací a observability.
• Service Mesh: síťová vrstva (sidecar) pro vzory mTLS, retry, circuit breaker, rate limiting a telemetry uvnitř mikroslužeb.
• Governance: katalog API, schvalování změn kontraktu, verze a životní cyklus, SLA/SLO.

Testování a kvalita: od kontraktu po provoz

• Contract-first: definujte OpenAPI/Proto dříve než implementaci; generujte stubs/SDK.
• Automatické testy: unit, integrační, kontraktové (spotřebitel ↔ producent), e2e, testy výkonu a zátěže.
• Mocky a simulace: rychlý vývoj klientů i serverů; deterministické scénáře.
• CI/CD: linting specifikace, generování klientů, bezpečnostní skeny závislostí a image, canary nasazení.

Monitorování, logování a observabilita

• Metriky: latence (p95/p99), chybovost, propustnost, saturace zdrojů, počet 4xx/5xx a 429 (limity).
• Logy: strukturované (JSON) s korelačními ID; maskování PII a tajemství.
• Trasování: distribuované tracing (OpenTelemetry); analýza závislostí a kořenových příčin.
• Alerting: SLO/SLA, detekce regresí a degradací, runbooky pro zásahy.

Bezpečnost dat a compliance

• Princip minimálních oprávnění: omezení tokenů, scopes, segmentace sítí a izolace tenantů.
• Validace a sanitace: server-side validace schématem, ochrana proti injekcím, limit velikosti payloadu.
• Šifrování: v klidu (disk, DB) i za běhu (TLS), správa klíčů (KMS, rotace, audit).
• Audit a regulace: záznamy přístupů, data retention, práva subjektů dat (mazání/oprava) a geografické limity.

Praktické návrhové vzory

• Partial update: PATCH s JSON Merge/Patch; jasně definujte pravidla konfliktů.
• Bulk operace: dávkové end-pointy s partial success a agregovanými chybami.
• Transakce napříč službami: Saga pattern s kompenzačními kroky místo dvoufázového commit.
• Stavové stroje: explicitní stavová pole a přechody; validace povolených změn.
• Mezivrstvy: DTO mapování, anti-corruption layer při integraci legacy systémů.

UX pro vývojáře: dokumentace, SDK a příklady

• Dokumentace: příklady požadavků/odpovědí, scénáře použití, matice chyb, limity a politiky.
• Klientská SDK: generujte z kontraktu (OpenAPI/Proto); verze synchronizujte s API.
• Playground: interaktivní konzole (Swagger UI, GraphiQL) a testovací prostředí se sandbox daty.
• Onboarding: registrace aplikací, správa klíčů, rotace tajemství a postupy pro incidenty.

Výběr stylu API podle potřeby

• REST/HTTP+JSON: interoperabilita, jednoduchost, veřejná i partnerská API.
• GraphQL: flexibilní dotazy klientů (mobilní/SPA), snížení počtu round-tripů.
• gRPC: vysoce výkonné interní mikroslužby, streaming, pevná schémata.
• SOAP: regulovaná odvětví a legacy 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

• N+1 dotazy: konsolidujte end-pointy, použijte includes/expansion nebo GraphQL joins.
• Breaking changes: contract-first a lintry schémat; semver a migrační okna.
• Nadměrná latence: cache, komprese, kolokační regiony, connection pooling, HTTP/2.
• Duplicitní zprávy: idempotence, exactly-once nerealistické – navrhujte at-least-once s deduplikací.
• Nejasné chyby: jednotný error model, korelační ID a dobrou dokumentaci.

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á bezpečnost, 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 vývoj i byznys.