Kurumsal API Tasarımı: REST vs GraphQL vs gRPC, Versiyonlama ve KVKK

API artık sadece uygulamalar arası veri köprüsü değil; modern kurumsal mimaride iş süreçlerinin canlı kontratı. Müşteri portali, mobile app, B2B entegrasyon, mikroservis ağı, AI agent — hepsi API üstünden konuşur. Yanlış tasarlanmış bir API 2-3 yıl içinde migration projesi yaratır; doğru tasarlanmış bir API 5-10 yıl ömür verir ve yeni use case'lere kolayca uyum sağlar. Kurumsal API mühendisliği, protokol seçiminden versiyonlama disiplinine, rate limiting'den audit log'a kadar her katmanda bilinçli karar gerektirir.

Bizim API entegrasyon mühendisliği ve SaaS platform mühendisliği hizmetlerimiz kapsamında son 30 ayda 19 kurumsal API tasarım/migration projesi yürüttük — finans, e-ticaret, sağlık, lojistik sektörlerinde. Kendi AIGENCY v4 platformumuzun public + internal API'ları da bu disiplin altında işliyor. Bu yazıda kurumsal API tasarımının yedi kritik kararını sırayla anlatıyoruz: protokol seçimi, sözleşme tasarımı, versiyonlama, rate limiting, kimlik doğrulama, audit log + KVKK akışı, monitoring + observability.

1. Protokol seçimi — REST, GraphQL, gRPC karar matrisi

API protokolü seçimi iskelet kararıdır — geçişi zor, ekosistemi belirler, ekip yetkinliğini şekillendirir. Üç ana seçenek (artı niche'ler):

REST (Representational State Transfer) — HTTP semantics üstünde resource-oriented API. Olgunluk + ekosistem en geniş. Strengths: cache (HTTP cache, CDN), debug (curl, Postman), dokümantasyon (OpenAPI 3.x sektör standardı), tool ekosistemi (Insomnia, Swagger UI, Stoplight). Weaknesses: over-fetching (server gönderir, client'ın kullanmadığı alanlar), under-fetching (tek ekran için N+1 request), versioning karmaşık.

GraphQL — Facebook 2015'te yayınladı, schema-first query language. Client'ın istediği alanları tam ister, server o kadar döner. Strengths: data minimization (KVKK avantajı), client team verimliliği (backend yenisini eklemeden yeni view), introspection + tooling (Apollo Studio, GraphiQL). Weaknesses: cache zor (POST request, URL-bazlı CDN cache çalışmaz, Apollo Cache veya Persisted Queries gerek), N+1 query problemi (resolver naive yazılırsa), monitoring karmaşık (her query farklı shape), rate limiting nontrivial (depth limit, complexity limit ayrı katman).

gRPC — Google 2016, HTTP/2 + Protocol Buffers (Protobuf) binary serialization. Service-to-service iletişim için optimize. Strengths: yüksek throughput + düşük latency (binary, multiplexing), bidirectional streaming native, strong typing (Protobuf IDL), polyglot (40+ dil için code generation). Weaknesses: browser native değil (gRPC-Web proxy gerek), debug zor (binary), public API'da nadir (third-party developer alışkanlığı yok).

Karar matrisi:

Senaryo	Önerilen	Neden
Public REST API (third-party developer)	REST + OpenAPI	Ekosistem, dokümantasyon, OAuth, Postman
Mobile app — backend (yüksek over-fetch riski)	GraphQL	Client kendi alanını çeker, mobile data tasarrufu
Web SPA — backend (basit CRUD)	REST	Cache, debug, learning curve düşük
Mikroservis-mikroservis (yüksek hacim)	gRPC	Performance, typing, streaming
Browser → backend (modern web)	REST veya tRPC	gRPC native değil
AI agent — tool ecosystem	REST + OpenAPI	LLM function calling ekosistem REST'e tuned
Banka core ↔ kanal entegrasyonu	gRPC + mTLS	Internal, performance + security
B2B kurumsal entegrasyon	REST + OpenAPI	Ortak standart, SDK üretimi

Hibrit pattern: public REST gateway + internal gRPC. Müşteri REST görür, backend microservice ağı gRPC ile konuşur. Bizim AIGENCY platformumuz tarafında public yüzey REST + token-bazlı authentication (dokümantasyon: aigency.dev/docs); LLM/agent function calling ekosisteminin REST'e tuned olması bu seçimi destekliyor.

Yaygın hata: GraphQL trend olduğu için seçmek. GraphQL doğru senaryoda muazzam, yanlış senaryoda (basit CRUD + 2 sayfa app) gereksiz karmaşıklık. Karar teknik fit'e bağlı, popülerliğe değil.

2. Sözleşme tasarımı — OpenAPI 3.x, contract-first vs code-first

Bir API'nın sözleşmesi (contract), endpoint'lerin URL'i + HTTP method + request shape + response shape + status code'ları + auth gereği + error format'ı tanımlayan yapılandırılmış spec. OpenAPI 3.x (eski Swagger) REST için sektör standardı, GraphQL için SDL (Schema Definition Language) zorunlu, gRPC için Protobuf .proto dosyaları zorunlu.

Contract-first (sözleşme önce):

1. Tasarımcı OpenAPI YAML/JSON yazar (openapi.yaml).
2. Stakeholder review — frontend, mobile, third-party developer gözden geçirir.
3. Mock server (Prism, Mockoon, Stoplight) ile frontend backend olmadan geliştirir.
4. Backend implementation sözleşmeye karşı yazılır.
5. Otomatik test (Schemathesis, Dredd) sözleşmeden generate, drift'i CI'da yakalar.

Code-first (kod önce):

1. Backend developer endpoint kodunu yazar (decorator + type annotation).
2. Framework (FastAPI, NestJS, tRPC) otomatik OpenAPI/SDL üretir.
3. Frontend backend hazır olunca client generate eder.

Hangisi doğru? Bizim deneyimimizden:

Senaryo	Yaklaşım	Sebep
Public/external API	Contract-first	Stakeholder review kritik, sözleşme commitment, breaking change disiplin
B2B partner entegrasyon	Contract-first	Sözleşme = hukuki commitment, partner ile önden anlaş
Internal microservice (tek ekip)	Code-first	Hızlı iterate, framework otomatize
Hızlı PoC / hackathon	Code-first	Sözleşme yazımı yavaşlatır
Çok-dilli ekip (TS + Python + Go)	Contract-first	Polyglot için tek truth source
Tek-dilli ekip (TypeScript only)	tRPC veya code-first	Type safety end-to-end, generate gereksiz

OpenAPI doc'unun gerçekten kullanılması için disiplin:

• CI pipeline'da openapi-validator çalışsın — geçersiz YAML push'unu reddet.
• Her PR'da openapi.yaml diff'i mandatory review (breaking change yakalama).
• openapi-diff aracı eski vs yeni schema karşılaştırır, semantic version bump'ı otomatik öner.
• Spectral lint rule'ları (alan adı camelCase, error response zorunlu, security scheme tanımlı, vs).
• Auto-generated SDK (TypeScript, Python, Go) her release sonrası npm/PyPI/GitHub Releases'a publish.
• Swagger UI veya Redoc ile public dokümantasyon — docs.your-api.com subdomain.

AI yönetişim çerçevemiz audit ve KVKK perspektifinden API sözleşmesinin zorunlu içeriklerini (security scheme, pii_field tag, data_retention header) detaylandırıyor.

3. Versiyonlama stratejisi — URL, header, lifecycle policy

Versiyonlama, public API'ın sürdürülebilirliğinin tek kritik faktörü. Yanlış strateji ya müşteriyi kızdırır (sürekli breaking change) ya backend'i çürütür (eski versiyon hiç ölmez, kod tabanı şişer).

URL versioning (/v1/users, /v2/users):

• Avantaj: debug kolay, Postman/curl direkt çalışır, cache friendly (URL = key), client URL'i hardcode'lar.
• Dezavantaj: aynı resource'un iki yerde olması, migration manuel.
• Bizim önerimiz: public REST API için default.

Header versioning (Accept: application/vnd.company.v2+json):

• Avantaj: URL temiz, RESTful püristlere uygun.
• Dezavantaj: debug zor (curl manuel header), CDN cache key header dahil tutulmalı (Vary header), client hata yapması kolay.
• Bizim önerimiz: sadece internal API için veya çok karşılıklı versionlama gereken niche.

Query parameter (/users?version=2):

• Hızlı prototip için iyi, production'da analytics + cache key karışır.
• Önermiyoruz.

Versiyon lifecycle policy (bu sözleşme yazıya bağlanır):

Aşama	Süre	Aksiyon
Active	Süresiz	Yeni feature, bug fix, breaking change → MINOR bump
Deprecated	12 ay	Deprecation + Sunset HTTP header, dokümantasyonda warning
Sunset announcement	3 ay öncesi	Tüm müşteriye email + dashboard banner
Sunset	Tarihte	Endpoint HTTP 410 Gone döner

Breaking change kuralı (MUST):

Değişiklik	Tip	Action
Yeni alan ekleme (response)	Non-breaking	MINOR bump
Yeni endpoint ekleme	Non-breaking	MINOR bump
Mevcut alan tipini değiştirme	Breaking	MAJOR bump, yeni version path
Mevcut alanı silme	Breaking	MAJOR bump
Required alan ekleme (request)	Breaking	MAJOR bump
Optional alan ekleme (request)	Non-breaking	MINOR bump
Error code değiştirme	Breaking	MAJOR bump
Authentication değişikliği	Breaking	MAJOR bump + ayrı announcement

Major version 2 yılda bir + extreme durumda. Her ay yeni major version çıkaran API güvenilmezdir — müşteri bağlı kalmaz.

4. Rate limiting + throttling — fair use + DDoS koruma

Rate limiting iyi vatandaşları korur, kötü vatandaşları durdurur. Üç katmanlı strateji:

Layer 1 — Global / DDoS koruma: CDN/WAF katmanında (Cloudflare, AWS Shield, Akamai). Saniyede 10.000+ request gibi geniş eşik, IP-bazlı. Amaç: volumetric attack durdurma.

Layer 2 — Per-API-key (fair use): müşteri tier'ına göre:

Tier	Rate limit	Burst	Aylık quota
Free	60 req/dakika	10 req	100K request
Pro	1.000 req/dakika	50 req	1M request
Enterprise	10.000+ req/dakika	200 req	Sınırsız (SLA'lı)

Sliding window algoritması fixed window'a göre daha pürüzsüz. Redis tabanlı counter:

INCR rate:user:{api_key}:{current_minute}
EXPIRE rate:user:{api_key}:{current_minute} 60
GET rate:user:{api_key}:{current_minute}

Token bucket algoritması burst kapasitesi sunar (ortalama 100 req/dakika ama anlık 50 req'lik patlamaya izin ver).

Layer 3 — Per-endpoint limit: pahalı endpoint'ler için ayrı limit. Örnek:

Endpoint	Maliyet	Limit
GET /users/{id}	Düşük (DB read)	Genel limit
POST /pdf/generate	Yüksek (PDF render 2sn)	10 req/dakika
POST /ai/inference	Çok yüksek (LLM)	5 req/dakika
POST /export/csv	Yüksek (DB scan)	3 req/dakika

HTTP response zorunlu:

• Limit aşıldığında: 429 Too Many Requests
• Header'lar:
  • X-RateLimit-Limit: 1000
  • X-RateLimit-Remaining: 0
  • X-RateLimit-Reset: 1716638400 (epoch)
  • Retry-After: 30 (saniye)

Müşteri usage dashboard zorunlu — kullanıcı kendi quota'sını görebilmeli, limit yaklaşma uyarısı (e-mail / webhook), aylık report.

KVKK perspektifi: brute-force koruma için POST /login endpoint'inde ek katman — failed attempt başına exponential backoff (1sn, 2sn, 4sn, 8sn...), 10 deneme sonrası 15dk lockout. CAPTCHA + MFA challenge entegrasyonu.

5. Authentication & authorization — OAuth 2.1, JWT, mTLS

Authentication = sen kimsin?; Authorization = ne yapabilirsin?. Kurumsal API'larda dört ana pattern:

API key (basit):

• X-API-Key: ak_live_xxxxx header.
• Server-to-server, kısa ömürlü değil, scope desteği zayıf.
• Public API'da çok yaygın (Stripe, OpenAI), internal'da yeterli olabilir.
• Rotation discipline kritik — leak durumunda hemen revoke + yeni key.

OAuth 2.1 + JWT (modern standart):

• Authorization server (Keycloak, Auth0, Okta, Cognito, Authentik) ile flow.
• Authorization Code Flow + PKCE (mobile + SPA), Client Credentials (server-to-server).
• Access token (short-lived, 15dk-1saat) + Refresh token (long-lived, 7-30 gün).
• JWT içinde sub, scope, exp, custom claim'ler. HS256 simetrik değil, RS256/ES256 asimetrik kullanın (key rotation kolaylaşır).
• Public + B2B kurumsal API için baskın seçim.

mTLS (mutual TLS):

• Her iki taraf (client + server) certificate sunar.
• Banka core ↔ kanal, sağlık sistem entegrasyonu, kritik altyapı için.
• mTLS + OAuth birlikte (defence in depth) high-security ortamlarda.

RBAC + ABAC + Scope:

Model	Tanım	Örnek
RBAC (Role-Based)	Kullanıcıya rol, role izin	"admin", "editor", "viewer"
ABAC (Attribute-Based)	Attribute'lar (department, region, time) kontrol	"Marketing dept + İstanbul ofis + 09-18 saat"
Scope (OAuth)	Token'a izin scope'u	users:read, orders:write
ReBAC (Relationship-Based)	İlişki grafiği	"this document's author can edit"

Pratik öneri: JWT scope (coarse-grained) + database-level RBAC (fine-grained). JWT'de read:users, write:users gibi geniş scope; database katmanında "bu user_id sadece kendi org'unun row'larını görebilir" gibi detay.

Token storage — browser'da localStorage XSS'e açık; httpOnly secure cookie tercih edilir. Mobile için keychain (iOS) / Keystore (Android).

KVKK pratik: kişisel veri içeren her API endpoint için scope zorunlu — read:user_profile scope'u olmayan client kişisel veriye dokunamamalı, request reddedilmeli (403 Forbidden).

6. Audit log + KVKK uyumlu kişisel veri akışı

Production API'ın en sık atlanan adımı audit log. KVKK ihlal araştırmasında, BDDK denetiminde, SOC 2 compliance'ta tek savunma — kim ne zaman hangi PII'ya dokundu doküman olmalı.

Minimum audit log alanları:

Alan	Örnek	Neden
timestamp	2026-05-25T14:32:17Z	Zamansal sıra
request_id	uuid v4	Distributed trace
api_key_id	ak_live_xxxxx	Kim (technical identity)
user_id	u_98234	Kim (business identity)
client_ip	203.0.113.42	Nereden
user_agent	Mozilla/5.0...	Hangi araç
http_method	GET	Aksiyon tipi
endpoint	/v2/users/{id}	Kaynak
query_params	?fields=name,email	Detay
response_status	200	Sonuç
response_time_ms	142	Performance
pii_fields_accessed	[name, email, phone]	KVKK kritik
auth_scope	read:users	Yetki

Log storage: immutable, append-only — Elasticsearch + ILM (Index Lifecycle Management) 90 gün hot + 2 yıl warm + 5 yıl cold (KVKK retention compliance). Cloud: AWS CloudWatch Logs + S3 Glacier, Azure Log Analytics + Blob archive. Erişim sadece compliance team (RBAC + MFA).

Field-level masking pattern (API gateway katmanında):

Original response:
{
  "user_id": "u_98234",
  "name": "Mehmet Yılmaz",
  "tc_kimlik": "12345678901",
  "iban": "TR33 0006 1005 1978 6457 8413 26",
  "phone": "+90 532 123 45 67"
}

Customer-service role:
{
  "user_id": "u_98234",
  "name": "Mehmet Yılmaz",
  "tc_kimlik": "***********",
  "iban": "TR33 **** **** **** **** **** 26",
  "phone": "+90 532 *** ** **"
}

Finance role:
{
  "user_id": "u_98234",
  "name": "Mehmet Yılmaz",
  "tc_kimlik": "12345678901",
  "iban": "TR33 0006 1005 1978 6457 8413 26",
  "phone": "+90 532 *** ** **"
}

Sparse fieldset (REST'te ?fields=..., GraphQL native) — client sadece ihtiyacı olan alanı çeker, gereksiz PII transit etmez. KVKK data minimization prensibinin teknik ifadesi.

Right to erasure (KVKK md. 11) — kişi silinme talebi geldiğinde:

1. Identity verification (kişi gerçekten bu kullanıcı mı?).
2. API endpoint: DELETE /users/{id} veya internal admin tool.
3. Hard delete (soft delete değil — sadece deleted_at column değil, gerçek silme).
4. Cascade delete (related orders, sessions, audit log içindeki PII alanlar).
5. Audit log'da silme eylemi notu (kim sildi, ne zaman — silinen kişinin kim olduğu detayı değil, sadece silme eylemi).
6. 30 gün içinde tamamlanması zorunlu.

Cross-border transfer: API client'ın bulunduğu ülke log'lanır; AB dışına PII gönderimi için Standard Contractual Clauses sözleşmeye eklenmeli + Türkçe tercüme.

7. Monitoring + observability — sadece çalışıyor değil, sağlıklı

Production API'sı çalışıyor yeterli değil; sağlıklı olmalı. Bu üç katman observability gerektirir:

Metrics (sayısal göstergeler):

Metrik	Hedef	Anlamı
Request rate	Trend takip	Hacim
Error rate (4xx + 5xx)	<%1 5xx, <%5 4xx	Sağlık
Latency p50	<100ms	Hızlı path
Latency p95	<500ms	Çoğu kullanıcı
Latency p99	<2sn	Worst case
Throughput (req/sn)	Capacity planning	Scaling sinyali
Active API key	Customer adoption	İş metriği
Rate limit hit rate	<%2	Tier doğru mu?

Prometheus + Grafana (open-source), Datadog/New Relic (managed), AWS CloudWatch/Azure Monitor (cloud-native).

Tracing (distributed): bir request 5 mikroservis dolaşıyorsa trace ID ile uçtan uca takip. OpenTelemetry standart, Jaeger/Tempo/AWS X-Ray backend. Latency bottleneck'i (hangi service uzun sürüyor?) tespit için kritik.

Logging (structured): JSON format, log level (DEBUG, INFO, WARN, ERROR), context (request_id, user_id, trace_id). Elasticsearch + Kibana, Loki + Grafana, Splunk. Audit log ayrı pipeline'da (immutable, compliance).

SLO + Error budget:

• SLO: 99.9% availability (43dk/ay downtime kabul).
• 99.95% (22dk/ay) — finansal/sağlık tier.
• 99.99% (4dk/ay) — kritik altyapı tier (multi-region active-active gerekir).
• Error budget tükenmesi → feature freeze, reliability work odak.

Alerting (PagerDuty, Opsgenie, Grafana OnCall):

• P1: 5xx rate >%5 (5dk sustain) → on-call'a SMS + telefon.
• P2: latency p99 >5sn (10dk sustain) → on-call'a SMS.
• P3: rate limit hit >%10 sustained → e-mail.
• P4: daily summary → Slack channel.

Status page (Statuspage.io, Instatus, self-hosted): kullanıcıya transparency. Incident → public update → resolution.

Veri mühendisliği altyapısı API metric + log pipeline'ı için sıklıkla kritik — Kafka, ETL, time-series database stack'i gerektirir.

Pratik özet — başlangıç check-list'i

İlk üretim API'ınız için doğru sıra:

1. Protokol seçimi: public = REST, mobile-heavy = GraphQL, internal microservice = gRPC. Hibrit OK.
2. Sözleşme tasarımı: contract-first (public/B2B), code-first (internal solo team). OpenAPI 3.x CI'da validate.
3. Versiyonlama: URL versioning default, 12 ay deprecated süresi, semantic version disiplini.
4. Auth: OAuth 2.1 + JWT (RS256), scope-based authorization, mTLS yüksek hassasiyet.
5. Rate limiting: 3 katman (DDoS + per-key + per-endpoint), sliding window + Redis, response header'ları zorunlu.
6. Audit log: timestamp + identity + endpoint + PII fields accessed. Immutable storage, 5+ yıl retention.
7. KVKK: scope + masking + sparse fieldset + hard delete pipeline. Cross-border transfer log.
8. OpenAPI doc: contract-first, auto-generated SDK, Swagger UI public.
9. Monitoring: metric + trace + log üç katman, SLO + error budget, alerting + status page.
10. Sürekli iyileştirme: client feedback, error analytics, deprecation roadmap, security review (yıllık pentest).

Bu liste minimum disiplin. Üzerine sektörel ek (PSD2 için OAuth flow, FHIR/HL7 için sağlık standardı, ISO 27001 için access control matrix) eklenir. Kurumsal API'ın değeri bugün çalışıyor olmasında değil, 3 yıl sonra hâlâ sürdürülebilir, dokümante, audit'lenebilir olmasında.

Bizim ekibimiz Şanlıurfa Karaköprü'den API entegrasyon mühendisliği ve SaaS platform mühendisliği ile finans, e-ticaret, sağlık, lojistik sektörlerinde 19 kurumsal API projesi yürüttü, kendi AIGENCY v4 platformumuzun API mimarisini de bu disiplinle işletiyoruz. Kurumsal API tasarımı, migration veya mevcut API'nızın olgunluk değerlendirmesi için iletişim formundan ulaşabilirsiniz — ilk değerlendirme görüşmesi ücretsizdir.

---

eCloud Tech — Şanlıurfa merkezli kurumsal yazılım, yapay zekâ, blockchain ve siber güvenlik ekibi. Building Tomorrow.