API‑first podniková architektura: moderní návrhové vzory a implementační playbook

API‑first slaďuje obchodní schopnosti s kvalitně navrženými rozhraními, která škálují napříč týmy a systémy. Tento návod přináší praktický plán: domény, kontrakty, gateway, eventy, bezpečnost, governance a postupnou migraci z point‑to‑point integrací na odolnou platformu.

Principy

- Domény před endpointy; schopnosti podle hranic domén, ne systémů - Kontrakty jako produkty: verzované, dokumentované, testované jako kód - Zpětná kompatibilita: aditivní evoluce; deprecace s telemetrií a termíny - Odolnost a idempotence by default - Observabilita a produktová vývojářská zkušenost (DX)

Domény a hranice

- DDD pro mapu domén: Matter, Dokumenty, Strany, Billing, Knowledge, Identita - Rozlišení interních vs. externích (klientských) API; úrovně soukromí - Anti‑corruption vrstva pro izolaci legacy

API kontrakty

- Modelování zdrojů: podstatná jména, vztahy, stránkování - Verzování: URI/hlavička; aditivní změny; sunset politika - Idempotence: klíče pro POST; ETag pro podmíněné updaty; bezpečné retry - Error model: problem+json, machine‑readable kódy, correlation ID - Metadata: konzistentní filtrování/řazení/stránkování

Bezpečnost a soukromí

- OAuth2/OIDC, mTLS; jemnozrnné scope - ABAC: claimy na úrovni matter; dynamické politiky v gateway i službě - Minimalizace dat: filtr polí; redakce logů; tokenizace PII

Gateway politiky

- API gateway pro auth, rate limit, validace, enforcement schémat - Spike arrest, token bucket; prioritní pruhy pro kritický traffic - Transformace request/response pro kompatibilitu

Eventy a asynchronní integrace

- Event‑driven pro decoupling: doménové eventy (DocumentClassified, ClauseDeviationScored) - Exactly‑once přes idempotentní konsumery + dedupe okna - Outbox vzor proti dual‑write problémům

Observabilita a kvalita

- Strukturované logy, trace, metriky (p95 latence, error rate, saturace) - Kontraktové testy v CI; consumer‑driven kontrakty - SLO pro API; error budgety řídí release

Developer experience

- Jednotný portál: katalog, dokumentace, try‑it, klíče, průvodci - Šablony pro nové služby; linting - Golden paths pro auth, stránkování, error model

Migrace z legacy

- Inventura integrací; mapování na domény a kanonické modely - Strangle pattern: legacy předložit novými API; postupný přesun schopností - Adaptéry pro klíčové konzumenty; odstraňování křehkých P2P vazeb

Referenční diagram (textově)

[Diagram] Klient/Partner → API Gateway → Doménové služby (Matters, Docs, Billing, Knowledge) → Event Bus → Konzumenti (CLM, Search, Analytics) → Observabilita a Governance

Jak BASAD pomáhá: BASAD staví API‑first platformy: definici domén, kontrakty, gateway politiky, eventing a DX. Implementujeme idempotentní, bezpečná API s jasnými SLO a kontraktovými testy a vedeme postupnou migraci z legacy s měřitelným snížením rizika.