api-paradigm-selection

API Paradigm Selection

Ortak Doktrin

agents/shared/severity-rubric.md ve agents/shared/escalation-matrix.md default-load sayılır (agents/coordination.md §11). Bu skill'in çıktısı Critical / High / Medium / Low + kanıt formatında olmak zorunda — spekülatif Critical yasak. Sahiplik dışı bulgu ilgili agent'a delege; karar yetkisi eşiği aşılırsa kullanıcı onayı zorunlu.

Felsefe

• Hybrid kabul — REST + gRPC + GraphQL + AsyncAPI aynı anda.
• Public vs internal ayrımı.
• Consumer profile önce, paradigma sonra.
• ADR her büyük paradigma kararı.
• Migration faz planlı — big-bang yok.

Ne Zaman Kullanılır

• Yeni API/servis ilk paradigma seçim
• Mevcut REST → GraphQL veya gRPC değerlendirme
• BFF tasarımı (mobile + web ayrı veya birleşik)
• Microservice extraction sonrası transport karar
• Public API partner onboarding (REST default)
• Event-driven decoupling (async migration)
• Browser native gRPC (grpc-web vs Connect)
• Apollo Federation evaluation (≥5 subgraph)
• "REST eski deyip GraphQL force" tartışmasında ölçüt

Workflow

1) Use case inventory

Soru	Cevap
Consumer?	browser / mobile / partner / internal service
Volume?	RPS, concurrent connection
Latency budget?	p50, p99
Bandwidth constraint?	mobile cellular, IoT
Streaming?	hayır / server→client / client→server / bidirectional
Caching?	edge CDN OK / personalized only
Schema evolution sıklığı?	weekly / monthly / quarterly
Public surface?	partner SDK / 3rd-party
Tooling maturity gerek?	full ecosystem / niche OK

2) Decision matrix

Public API (partner / 3rd-party)

→ REST + OpenAPI 3 default

• Cacheable, browser native, partner SDK kolay
• Webhook async (HMAC sign)
• URL versioning (/v1/, /v2/)
• Rate limit headers

GraphQL public alternative:

• Adopt ancak partner ekosistem ≤ 10 + flexible query gerek + rate-limit query-complexity-aware tooling olgun.

Internal service-to-service

→ gRPC + Protobuf default

• Düşük latency, binary, streaming, strong typing, polyglot codegen
• mTLS + mesh native
• HTTP/2 multiplex

REST internal alternative:

• Legacy migration sırasında veya tooling gap'te.

Mobile / Web BFF

→ GraphQL (over-fetch eliminate) veya REST (basitlik)

Hybrid:

• BFF GraphQL + internal gRPC = en yaygın 2026 mimarisi
• Apollo Federation ≥ 5 subgraph + dedicated platform team

Event-driven async

→ AsyncAPI + Kafka/NATS/RabbitMQ/SQS

• Producer-consumer decoupling, fan-out, retry/DLQ
• /data-contracts skill bağı

WebHook fallback:

• At-most-once delivery; küçük volume; eventual consistency tolere edilir.

Real-time bi-directional

→ WebSocket

• /websocket-debug skill
• Proxy-aware (idle disconnect, reconnect storm)

Streaming server → client

→ SSE veya WebSocket

• SSE: tek yön, HTTP-friendly, reconnect built-in
• WS: bi-directional gerek varsa

3) Hybrid pattern karar

BFF:

[mobile] [web] → [GraphQL BFF] → [gRPC service mesh]
[partner]      → [REST API]    → [gRPC service mesh]

Apollo Federation:

[GraphQL gateway] ── compose ──┬─ Users subgraph (Go gRPC backend)
                                ├─ Orders subgraph (Python REST backend)
                                └─ Inventory subgraph (Node gRPC)

grpc-gateway (proto annotation → REST mirror):

service OrderService {
  rpc GetOrder(GetOrderRequest) returns (Order) {
    option (google.api.http) = { get: "/v1/orders/{order_id}" };
  }
}

Connect (Buf): tek handler — gRPC + Connect + browser; bundle ~10KB.

4) ADR yaz

/architecture-decision-writer delege.

# ADR-00X: Adopt GraphQL BFF + gRPC internal

## Context
Mobile + web 4 platform; ortalama 8 downstream service aggregate. Mobile
over-fetch p95 1.8MB; mobile bandwidth maliyet yüksek; client-side stitching
karışık.

## Decision
- BFF: GraphQL (Apollo Server)
- Internal: gRPC (existing)
- Public partner API: REST mevcut kalır

## Alternatives
- A. Tek REST BFF: over-fetch devam (mobile +30% data)
- B. Tek gRPC: browser native değil; grpc-web bundle +20KB; flexible
     query yok
- C. Apollo Federation: ≤ 5 subgraph (henüz 2); premature

## Consequences
- (+) Mobile data -%40
- (+) Frontend velocity (single query)
- (-) GraphQL N+1 problem; DataLoader gerek
- (-) Caching kompleks; persisted queries gerek
- (-) Rate limit query-complexity-based

5) Migration faz planı

Yeni paradigma adoption:

Phase 1 (1 ay): Pilot 1 endpoint paralel (REST + yeni)
Phase 2 (2 ay): Top 5 endpoint migrate (shadow read)
Phase 3 (3 ay): Consumer migrate (deprecation header)
Phase 4 (3 ay): Eski paradigma sunset

Big-bang yasak.

6) Tooling kur

Paradigma	Tooling
REST	OpenAPI Generator, Swagger UI, Postman, Pact, schemathesis
GraphQL	Apollo Server/Studio, Hasura, urql, graphql-codegen
gRPC	buf, grpcurl, otelgrpc, Connect
AsyncAPI	AsyncAPI Studio, Schema Registry, schemathesis
WebSocket	k6 ws, Postman, wscat

7) Versioning karar

Her paradigma için:

Paradigma	Versioning
REST	URL /v1/... + RFC 9745 Deprecation header
gRPC	proto package v1, v2; field number reserved
GraphQL	@deprecated directive; schema versioning yok
AsyncAPI	topic events.X.v1; Schema Registry compat

/semantic-versioning bağı.

Checklist

• Use case inventory (consumer + volume + latency + streaming + caching)
• Public vs internal ayrımı
• Decision matrix uygulandı
• Hybrid pattern uygun mu (BFF / federation / gateway / Connect)
• ADR yazıldı
• Migration faz planı (mevcut → yeni paradigma)
• Tooling olgunluğu kontrol
• Versioning strategy paradigma'ya uygun
• Browser native gerek (gRPC ise grpc-web/Connect)
• Caching strategy (REST CDN; GraphQL persisted query; gRPC LB)

Antipattern

• Tek paradigma force.
• Public API gRPC raw.
• Internal REST performance-critical.
• GraphQL public caching + rate-limit analizsiz.
• WebSocket pub/sub-only (SSE/AsyncAPI yeterli).
• AsyncAPI sync UX'te.
• Apollo Federation premature.
• REST eski sayıp greenfield kullanmamak.
• grpc-web tüm streaming bekler.
• GraphQL versioning yok.
• AsyncAPI topic versioning yok.
• Paradigma karar ADR'siz.

Örnek Agent Davranışı

User: /api-paradigm new-svc (mobile + web + partner consumer; çoklu downstream)
Agent (system-design-architect + api-contract-guardian):

1. Use case inventory:
   - Consumer: iOS, Android, web SPA, 3 partner SDK
   - Volume: 800 RPS sustained
   - Latency: p99 < 300ms client; p99 < 100ms internal
   - Streaming: server-stream notifications (Phase 2)
   - Cache: 60% read product catalog; CDN gerek

2. Decision matrix:
   - Internal: gRPC (existing mesh, mTLS, polyglot, perf)
   - Mobile + web: GraphQL BFF (over-fetch -%40 mobile)
   - Partner: REST (existing SDK, ekosistem)
   - Notifications: SSE (tek yön, HTTP-friendly, reconnect)
   - Events: AsyncAPI Kafka (existing pipeline)

3. ADR-0099 yazıldı (alternatif: tek REST BFF, tek gRPC, Federation).

4. Migration plan:
   - Phase 1 (1 ay): GraphQL BFF pilot 5 endpoint
   - Phase 2 (2 ay): Apollo persisted queries + DataLoader
   - Phase 3 (3 ay): SSE notifications
   - REST partner API as-is (sustaining)

5. Tooling: Apollo Server v4, graphql-codegen TS types, persisted query DB,
   query complexity rate-limiter.

6. Versioning:
   - GraphQL: `@deprecated` directive
   - REST partner: URL /v1, /v2 (`/semantic-versioning`)
   - gRPC internal: proto package v1 (`/data-contracts`)

Çıktı Formatı

# API Paradigm Selection: <service-or-system>

## Use case inventory
- Consumer profile + volume + latency + streaming + cache

## Decision per use case
- Public partner: REST
- Internal: gRPC
- BFF: GraphQL veya REST
- Async: AsyncAPI
- Real-time: WebSocket / SSE

## Hybrid pattern
- BFF / Federation / gateway / Connect

## ADR
- Decision + alternatives + consequences

## Migration plan (varsa)
- Phase 1-N

## Tooling

## Versioning per paradigma

## Action Items
| P | Aksiyon | Sahip | Bitiş |