API Contract ve Tooling

API-first yaklaşımda sözleşme, implementasyondan önce istemci ve sunucu ekiplerinin ortak çıktısıdır. OpenAPI veya GraphQL şeması yalnızca dokümantasyon değil; validation, mock, generated client, contract test ve değişiklik kontrolü için kullanılabilir.

Hızlı Karar

İhtiyaç	Yaklaşım	Dikkat
HTTP API sözleşmesi	OpenAPI	Runtime davranışla drift etmemeli
GraphQL sözleşmesi	SDL schema	Resolver davranışı ayrıca test edilmeli
Tüketici güveni	Consumer-driven contract	Provider pipeline'a bağlanmalı
Çok dilli istemci	Generated SDK	Şema değişiklikleri breaking olabilir
Geliştirici onboarding'i	Interactive docs + examples	Örnekler gerçek auth ve hata modelini göstermeli

Üretim Kontrol Listesi

• Problem: Sözleşmenin sahibi kim ve hangi değişiklik breaking kabul ediliyor?
• Çözüm: Lint, mock, generated artifact, contract test ve docs pipeline içinde mi?
• Trade-off: Erken sözleşme paralel geliştirmeyi sağlar; yanlış contract değişikliği birçok tüketiciyi etkiler.
• Hata durumu: Drift, eksik örnek, yanlış status code, incompatible schema ve stale SDK izlenmeli.
• Ölçüm: Contract test coverage, breaking-change count, SDK adoption ve docs usage takip edilmeli.
• Güvenlik/maliyet: Örnek credential kullanma; private schema ve developer portal erişimi yetkilendirilmeli.

API-First ve OpenAPI

OpenAPI içinde path, operation, parameters, request body, response schemas, error responses, auth scopes ve examples bulunur. Schema'dan server stub, client model, mock server ve documentation üretilebilir; ancak generated code iş kuralı yerine geçmez.

openapi: 3.0.3
paths:
  /orders/{id}:
    get:
      operationId: getOrder
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      responses:
        '200': { description: Order found }
        '404': { $ref: '#/components/responses/NotFound' }

CI'da schema lint, backward-compatibility diff ve generated artifact kontrolü çalıştırılmalı. Runtime endpoint'inin gerçek response'u sözleşmeyle düzenli karşılaştırılmalıdır.

Contract Testing

Consumer-driven contract'ta tüketici, gerçekten kullandığı istek/yanıt beklentisini yayınlar; provider pipeline'ı bu beklentiyi doğrular. Pact gibi broker tabanlı araçlar sürüm ve consumer/provider uyumluluğunu takip eder. Spring Cloud Contract, provider stub ve test üretimini Spring ekosistemine bağlar.

Contract test, integration test'in yerine geçmez: dış servisin temel davranış sözleşmesini doğrular; database, queue ve gerçek üçüncü parti entegrasyonu ayrıca test edilir. Contract değişikliği önce additive yapılmalı, consumer migration tamamlanmadan alan silinmemelidir.

Mocking ve SDK Generation

Mock server, frontend ve mobil ekiplerinin backend hazır olmadan ilerlemesini sağlar; mock'lar üretim sözleşmesinden türetilmeli ve gerçek response örnekleriyle drift kontrolü yapılmalıdır.

Generated SDK için şu politikalar açık olmalıdır:

• Dil ve runtime sürümü, package naming ve release versioning.
• Auth, timeout, retry, pagination ve error mapping davranışı.
• Breaking change sonrası major version ve deprecation süresi.
• Idempotency header'ları ve request/correlation ID propagation.

SDK, HTTP hatalarını yutan ince bir wrapper olmamalı; response metadata ve stable error code'ları type-safe biçimde sunmalıdır.

Interactive Documentation ve Developer Portal

Swagger UI veya benzeri interactive docs; endpoint örnekleri, auth akışı, hata cevapları ve curl/Java örneklerini göstermelidir. GraphQL Playground benzeri araçlar introspection ve production veri erişimi için güvenli ortama bağlanmalıdır.

Developer portal, API kataloğu, sahiplik, lifecycle, changelog, quickstart, rate limit, support kanalı ve SDK bağlantılarını bir araya getirir. Portal bilgisi source contract ve release pipeline'dan otomatik güncellenmiyorsa kısa sürede güven kaybeder.

Release Akışı

1. Contract değişikliğini schema diff ile sınıflandır.
2. Mock ve consumer contract test'lerini çalıştır.
3. Server/client artifact ve dokümanı aynı sürümle üret.
4. Deprecation ve migration notunu yayınla.
5. Trafik, error rate ve eski sürüm kullanımını izleyerek kaldırma tarihini uygula.

Bu sayfa, REST ayrıntıları için REST API Tasarımı, GraphQL ayrıntıları için GraphQL API ile birlikte okunmalıdır.