Máte microservices, máte Kubernetes, máte CI/CD pipeline. Ale když přijde nový tým a potřebuje integrovat svou službu s vaším systémem, stráví dva týdny čtením Slack zpráv a reverse-engineeringem HTTP volání z logu. Tohle je důvod, proč API-first architektura není luxus — je to základ, bez kterého se enterprise systémy v roce 2026 neobejdou.
Co znamená API-first — a co to neznamená¶
API-first neznamená „máme REST endpointy.” Znamená to, že API kontrakt je první artefakt, který vznikne při návrhu jakékoli služby — dřív než kód, dřív než databázové schéma, dřív než UI mockupy. Kontrakt se stává zdrojem pravdy, kolem kterého se organizuje celý vývojový proces.
V praxi to vypadá tak, že architekti a vývojáři nejprve definují OpenAPI specifikaci (nebo gRPC proto soubor, nebo GraphQL schéma), nechají ji projít review, a teprve pak začnou paralelně pracovat — backend implementuje kontrakt, frontend generuje klienta z kontraktu, QA tým generuje testy z kontraktu. Nikdo na nikoho nečeká.
Co API-first neznamená: není to dogma „všechno musí být REST.” Moderní API-first přístup je multi-protocol — REST pro public-facing API, gRPC pro interní service-to-service komunikaci, GraphQL pro frontend BFF (Backend for Frontend) vrstvu, a async eventy přes Kafka nebo NATS pro event-driven flows.
OpenAPI 3.1 — konečně plná kompatibilita s JSON Schema¶
OpenAPI 3.1, dnes de facto standard pro definici REST API, přinesl zásadní změnu: plnou kompatibilitu s JSON Schema Draft 2020-12. To znamená konec ér, kdy jste museli udržovat dvě verze schémat — jedno pro validaci, jedno pro OpenAPI. Jedno schéma, jeden zdroj pravdy.
V enterprise kontextu je tohle klíčové. Schémata definovaná v OpenAPI specifikaci můžete přímo použít pro runtime validaci (request/response), pro generování klientských SDK (openapi-generator podporuje 40+ jazyků), pro contract testing v CI/CD (Schemathesis, Dredd), a pro automatickou dokumentaci (Redocly, Stoplight).
`# OpenAPI 3.1 — příklad contract-first definice
openapi: “3.1.0”
info:
title: Order Service API
version: “2.4.0”
description: Manages order lifecycle
paths:
/orders:
post:
operationId: createOrder
requestBody:
required: true
content:
application/json:
schema:
$ref: “#/components/schemas/CreateOrderRequest”
responses:
“201”:
description: Order created
content:
application/json:
schema:
$ref: “#/components/schemas/Order”`
Klíčový pattern: spectral linting v CI pipeline. Nástroj Spectral od Stoplight umožňuje definovat pravidla pro API design (naming conventions, pagination patterns, error format) a vynutit je automaticky při každém merge requestu. Žádné „zapomněli jsme na pagination” v review.
gRPC pro interní komunikaci — proč ne REST všude¶
REST je skvělý pro public API — je jednoduchý, univerzální, funguje s jakýmkoli HTTP klientem. Ale pro interní service-to-service komunikaci v microservices architektuře má zásadní limity: textový JSON formát je pomalý na serializaci, HTTP/1.1 nemá multiplexing, a schema enforcement závisí na dobrovolné disciplíně.
gRPC řeší všechny tři problémy. Používá Protocol Buffers (protobuf) pro binární serializaci — 5–10× menší payload než JSON, 10–100× rychlejší parsing. Běží nad HTTP/2 s multiplexingem, streamy a header compression. A .proto soubory jsou striktní kontrakty — kompilátor vám nedovolí odeslat nevalidní zprávu.
`// order_service.proto — gRPC contract definition
syntax = “proto3”;
package cz.core.orders.v2;
service OrderService {
rpc CreateOrder(CreateOrderRequest) returns (Order);
rpc GetOrder(GetOrderRequest) returns (Order);
rpc StreamOrderUpdates(GetOrderRequest)
returns (stream OrderUpdate); // server-side streaming
}
message CreateOrderRequest {
string customer_id = 1;
repeated OrderItem items = 2;
string currency = 3;
}
message Order {
string order_id = 1;
OrderStatus status = 2;
google.protobuf.Timestamp created_at = 3;
}`
V praxi vidíme jasný pattern: gRPC pro east-west traffic (service-to-service), REST/GraphQL pro north-south traffic (klient → API gateway → služby). API gateway (Kong, Envoy, AWS API Gateway) funguje jako protocol translator — externě nabízí REST, interně routuje na gRPC. Klient neví a nepotřebuje vědět.
GraphQL Federation — unified API pro frontend¶
Máte 15 microservices. Každá má své REST API. Frontend potřebuje data z pěti z nich na jednu stránku. Výsledek? Pět HTTP volání, over-fetching, waterfall latence, a frontend vývojář, který tráví víc času orchestrací API volání než stavbou UI.
GraphQL Federation (Apollo Federation v2 / Grafbase) řeší tento problém elegantně. Každá služba definuje svůj GraphQL subgraph — schéma s typy, které spravuje. Federation router (Apollo Router, Grafbase Gateway) tyto subgraphy automaticky kompozituje do jednoho unified grafu. Frontend vidí jedno API, pošle jeden dotaz, router rozloží dotaz na subgraphy a složí odpověď.
Klíčová výhoda pro enterprise: domain ownership zůstává. Tým, který vlastní Order Service, spravuje svůj subgraph. Tým, který vlastní Payment Service, spravuje svůj. Nikdo nemá „God schema” — a přesto frontend dostane konzistentní, typované API.
Ale pozor na úskalí: GraphQL Federation vyžaduje query cost analysis (zabránění N+1 dotazům a DoS přes hluboký nesting), persisted queries (předkompilované dotazy místo libovolných stringů v produkci), a schema registry s composition validation v CI — jinak jeden tým může zlomit celý supergraph.
API Gateway jako enforcement layer¶
API gateway přestal být jen reverse proxy s rate limiting. V roce 2026 je to centrální enforcement point pro autentizaci, autorizaci, observability a traffic management — a v API-first architektuře hraje klíčovou roli.
- Kong Gateway / Kong Konnect: open-source základ s enterprise správou. Plugin ekosystém pro OAuth2, mTLS, request transformation. Silný v multi-cloud prostředích.
- Envoy Proxy: low-level, extrémně výkonný. De facto standard v service mesh (Istio). Ideální jako sidecar proxy pro gRPC i REST.
- AWS API Gateway + Lambda: serverless-native. Automatické škálování, nulová správa infrastruktury. Omezený pro komplexní transformace.
- Tyk, Gravitee: open-source alternativy s GraphQL Federation podporou a built-in developer portálem.
Kritický pattern: contract validation na gateway. Gateway validuje příchozí requesty proti OpenAPI specifikaci ještě před tím, než je pošle na backend službu. Nevalidní requesty se zamítnou na perimetru — backend nikdy nevidí malformovaná data. Tohle dramaticky snižuje attack surface i bug surface.
Contract Testing v CI/CD — klíč k paralelnímu vývoji¶
API-first architektura bez automatizovaného contract testing je jen dokumentace, která zastarává. V praxi potřebujete dva typy testů:
- Provider contract tests: ověřují, že implementace služby odpovídá jejímu OpenAPI/proto kontraktu. Nástroje: Schemathesis (fuzz testing proti OpenAPI), Prism (mock server z OpenAPI), buf (breaking change detection pro protobuf).
- Consumer-driven contract tests: ověřují, že změna v API nezlomí existující konzumenty. Nástroje: Pact (de facto standard), Spring Cloud Contract. Consumer definuje „co potřebuji od API” a provider to validuje v CI.
V enterprise prostředí kombinujeme oba přístupy. Provider tests běží při každém commitu na službu. Consumer-driven tests běží cross-repository — když Order Service změní API, automaticky se spustí contract testy všech služeb, které Order Service konzumují. Breaking change se zachytí před mergem, ne v pátek večer v produkci.
`# CI pipeline — contract validation step
contract-test:
stage: test
script:
# Lint OpenAPI spec against design rules
- npx @stoplight/spectral-cli lint openapi.yaml
# Fuzz test: auto-generated requests against spec
- schemathesis run openapi.yaml –base-url $SERVICE_URL
# Breaking change detection for protobuf
- buf breaking –against .git#branch=main
# Consumer contract verification
- pact-verifier –provider order-service –pact-broker $PACT_URL`
API Versioning — breaking changes bez breaking produkce¶
Každé API se vyvíjí. Otázka není, jestli budete potřebovat breaking change, ale jak ho provedete bez výpadku pro existující klienty. V roce 2026 se ustálily tři přístupy:
- URL versioning (
/v2/orders): nejjednodušší, nejčitelnější. Vhodné pro public API. Nevýhoda: duplikace kódu při údržbě starých verzí. - Header versioning (
Api-Version: 2): čistší URL, ale méně discoverable. Vhodné pro interní API s kontrolovanými klienty. - Evolution bez verzí: additive-only changes, deprecated fields s sunset headers. Funguje s OpenAPI 3.1 discriminator a nullable typy. Preferujeme pro gRPC (protobuf je nativně backward-compatible).
Náš pragmatický přístup: public REST API používá URL versioning s explicitním sunset policy (deprecated verze žije 12 měsíců). Interní gRPC služby používají protobuf evolution rules — nová pole mají nové field numbers, stará se nikdy nerecyklují. GraphQL by ze své podstaty neměl mít verze — místo toho deprecated direktivy na field úrovni.
Jak to stavíme v CORE SYSTEMS¶
API-first architektura není jednorázové rozhodnutí — je to kulturní změna v tom, jak organizace přemýšlí o komunikaci mezi systémy. V CORE SYSTEMS máme ověřený framework pro její zavedení.
Začínáme API Design Workshopem, kde s business a technickými stakeholdery mapujeme bounded contexty a definujeme, které služby potřebují jaké kontrakty. Výstupem je API landscape mapa — kdo s kým komunikuje, jakým protokolem, a kde jsou kritické závislosti.
Pak zavádíme API Design Guidelines — interní standard organizace pro naming conventions, error formát (RFC 9457 Problem Details), pagination, filtrování a versioning. Tyto guidelines formalizujeme jako Spectral ruleset, který se automaticky vynucuje v CI/CD.
Náš stack: OpenAPI 3.1 pro REST kontrakty, buf pro správu protobuf schémat, Apollo Federation pro GraphQL supergraph, Kong nebo Envoy jako API gateway, Backstage jako developer portal s automaticky generovanou dokumentací, a Pact + Schemathesis pro contract testing v CI/CD. Celý lifecycle API — od návrhu přes implementaci po deprecation — je automatizovaný a auditovatelný.
Závěr: API jako produkt, ne jako vedlejší efekt¶
API-first architektura mění perspektivu: API není technický detail implementace, je to produkt, který má své uživatele, svůj lifecycle a svou kvalitu. Když s API zacházíte jako s produktem — navrhujete ho, dokumentujete, testujete, verzujete a měříte — získáváte systémy, které se dají škálovat nejen technicky, ale i organizačně.
V roce 2026 to není volba mezi REST, gRPC a GraphQL. Je to multi-protocol strategie, kde každý protokol hraje svou roli. A contract-first design je lepidlo, které drží celý ekosystém pohromadě. Bez něj máte jen hromadu služeb, které se náhodou volají. S ním máte platformu.