1. GİRİŞ

API (Application Programming Interface) modern yazılımın merkezindedir. Mikroservislerin, mobil uygulamaların, üçüncü taraf entegrasyonlarının ve frontend‑backend ayrışmasının temelini API'ler oluşturur. İyi tasarlanmış bir API, sadece teknik bir arabirim değil; ekipler arası iletişimi, sürüm yönetimini ve ürünün ölçeklenebilirliğini doğrudan etkileyen bir sözleşmedir.

Neden bugün önemli?

• Bulut‑native ve mikroservis mimarileri API-first yaklaşımlar talep ediyor.
• Mobil, web ve IoT istemcileri farklı beklentilerle API'leri tüketiyor—uyumluluk ve performans kritik.
• AI/ML ve üçüncü parti entegrasyonları API'ler üzerinden büyüyor; değişime açık, iyi belgelenmiş API'ler hız kazandırır.

Kimler için önemli?

• Backend geliştiriciler ve yazılım mimarları
• API Gateway, platform ve SRE ekipleri
• Ürün yöneticileri ve üçüncü taraf entegrasyon ekipleri

Hangi problemleri çözüyor?

• Sistemler arası güvenilir entegrasyon
• Değişimlerde geriye dönük uyumluluk (backward compatibility)
• Güvenlik, gözlemlenebilirlik ve performans ihtiyaçlarının merkezileştirilmesi

2. KAVRAMSAL TEMELLER

2.1 API kavramları ve terminoloji

Contract (Sözleşme)

API'nin tüketiciye sunduğu fonksiyonellik, veri modelleri ve davranışları tanımlayan doküman ve kurallar bütünü.

Idempotency

Aynı isteğin birden çok kez tekrarlanmasının sonucu değişmemeli; özellikle ödeme veya sipariş gibi işlemlerde önemlidir.

Versioning

API değişikliklerinin tüketicileri kırmadan uygulanmasını sağlayan stratejiler (URI versiyonlama, header versiyonlama, content negotiation).

Rate limiting

API tüketimini kontrol altına almak ve abuse karşısında sistemi korumak için istek hızını sınırlama.

2.2 Yaygın API stilleri

• REST: Kaynak merkezli, HTTP semantiklerine dayalı, geniş benimsenmiş bir yaklaşımdır.
• GraphQL: İstemcinin ihtiyaç duyduğu alanları belirtmesini sağlayan sorgu dili; over/underfetching problemlerini azaltır.
• gRPC: Protobuf tabanlı, yüksek performanslı binary RPC; düşük gecikme gerektiren servisler için uygundur.
• Event‑driven APIs: Webhook'lar, message bus ve event streams ile asenkron entegrasyonlar sağlar.

3. NASIL ÇALIŞIR? — TEKNİK MİMARİ VE TASARIM PRİNSİPLERİ

3.1 API‑first yaklaşımı

API‑first: Önce API sözleşmesini (OpenAPI / AsyncAPI / Protobuf) tanımlamak, ardından implementasyona geçmek demektir. Bu yaklaşım, ekiplerin paralel çalışmasını, otomatik dokümantasyon ve contract testing'i kolaylaştırır. API spec tek gerçek kaynak (source of truth) olmalıdır.

3.2 Kaynak modelleme ve URI tasarımı (REST için)

• Kaynaklar çoğullaştırılmış isimlerle ifade edilir: /orders, /customers
• HTTP metodları semantics'e uygun kullanılmalıdır: GET (oku), POST (yarat), PUT/PATCH (güncelle), DELETE (sil)
• Hiyerarşi ve ilişkiler doğru yansıtılmalı: /customers/{id}/orders
• Filtreleme, sıralama ve sayfalandırma query parametreleriyle sağlanmalı (örn. ?page=2&size=50&sort=-createdAt)

3.3 Veri modelleme: Entity vs DTO vs Projection

Domain entity'leri doğrudan API payload'ı olmamalıdır. DTO'lar (Data Transfer Objects) ile iç modeliniz ve dış temsil ayrılmalıdır. Projection'lar veya view modelleri, performans ve ihtiyaçlara göre özelleştirilmelidir—özellikle read‑heavy senaryolarda (CQRS) önem kazanır.

3.4 Versiyonlama stratejileri

Versiyonlama için yaygın yöntemler:

• URI versiyonlama: /v1/orders — açık fakat URL'leri kirleten bir yaklaşım.
• Header versiyonlama: Accept: application/vnd.myapi.v2+json — daha RESTful fakat uygulaması karmaşık olabilir.
• Semantic versioning + contract evolution: Breaking changes API spec'te açıkça işaretlenir; backward compatibility öncelenir.

3.5 Hata mesajları ve durum kodları

Tutarlı hata yapıları ve HTTP durum kodu kullanımı önemlidir. Örnek bir hata schema'sı:

{
  "timestamp": "2026-03-14T12:00:00Z",
  "status": 400,
  "error": "Bad Request",
  "message": "validation failed",
  "errors": [{"field":"email","message":"invalid format"}],
  "traceId":"abc-123"
}

4xx kodları client hatalarını, 5xx kodları server hatalarını temsil eder. Hata mesajları machinable (parsable) ve intention revealing olmalıdır.

3.6 Idempotency ve güvenli operasyonlar

Özellikle ödeme veya sipariş gibi kritik işlemlerde idempotency anahtarı (Idempotency‑Key header) kullanılmalıdır. PUT genelde idempotent, POST ise non‑idempotent kabul edilir; ancak POST operasyonlarında da idempotency sağlanabilir.

3.7 Asenkron işlemler ve event‑driven design

Uzun süreli işler (background processing) için synchronous blocking yerine asenkron pattern'ler kullanın: request → 202 Accepted + location header (status endpoint) veya event publish → worker. Event schemas (CloudEvents) ve good‑practice event naming (domain.action) benimsenmelidir.

3.8 Güvenlik: Authentication ve Authorization

• OAuth2 / OpenID Connect ile kimlik ve yetki yönetimi; short‑lived tokens, refresh tokens ve scopes kullanımı.
• Least privilege: API token'lara sadece gerekli izinler verilmeli; admin token'ları kısıtlı kullanılmalı.
• Input validation, schema validation (JSON Schema / Protobuf validation) ile injection riskleri azaltılmalı.
• Transport security: TLS zorunlu, HSTS, ve secure cookie politikaları uygulanmalı.

3.9 Rate limiting, throttling ve quota yönetimi

Rate limiting uygulamanın kullanılabilirliğini korunmasına yardımcı olur. Rate limiting stratejileri:

• Leaky bucket veya token bucket algoritmaları
• Per‑api key, per‑ip, per‑tenant bazlı kotalar
• 429 Too Many Requests dönerken Retry‑After header ile öneri verin

3.10 Observability ve tracing

API çağrıları için correlation id (traceId) her istekte yer almalı ve log/trace/metriklere eklenmelidir. OpenTelemetry veya provider‑native tracing ile distributed trace toplanmalı. Business KPI'lar (orders/sec, checkout latency) ile infra metrikleri korelasyonu sağlanmalı.

4. GERÇEK DÜNYA KULLANIMLARI

4.1 Stripe — API olarak ürün (Product‑led API)

Stripe API'si tasarımında consistency, idempotency ve mükemmel dokümantasyon öne çıkar. Hataları anlamlandıran detaylı hata yapıları, müşteri‑merkezli hata mesajları ve client SDK'lar ile entegrasyon kolaylaştırılmıştır. Stripe, API-first bir ürün olarak örnek gösterilir.

4.2 GitHub & Google APIs — versiyonlama ve uyumluluk

Büyük platformlar geriye dönük uyumluluğu korumak için versiyonlama stratejileri, deprecate süreçleri ve otomatik migration yolları kullanır. Google API'lerinde protobuf ve gRPC ile verimli binary iletişim tercih edilirken REST endpoint'lerde geniş dokümantasyon sağlanır.

4.3 Netflix — ölçek ve gözlemlenebilirlik

Netflix'in mikroservis ekosistemi, API gateway'ler, rate limiting, client side resilience (resilience4j), ve zengin observability ile büyük ölçekli API tasarımının örneğidir. Circuit breaker, bulkhead ve retry stratejileri ile hizmet sürekliliği sağlanır.

5. AVANTAJLAR VE SINIRLAMALAR

Avantajlar

• İyi tasarlanmış API'ler entegrasyonu hızlandırır ve teknik borcu azaltır.
• Contract testing ve API‑first ile ekipler paralel çalışabilir.
• Observability ve SLO odaklı geliştirme operasyonel güvenilirliği artırır.

Sınırlamalar

• Fazla soyutlama kötü API tasarımına yol açabilir—kullanıcı ihtiyaçlarını göz ardı etmeyin.
• Versioning karmaşası ve backward compatibility yönetimi operasyonel maliyet getirir.
• GraphQL veya gRPC gibi teknolojilerin yanlış kullanımı performans veya complexity sorunları yaratabilir.

6. ALTERNATİFLER VE KARŞILAŞTIRMA

7. EN İYİ PRATİKLER

Production kullanımı

• API contract'ını OpenAPI/Proto dosyası olarak saklayın; CI ile contract testing uygulayın.
• Backward compatibility'yi koruyarak breaking change'leri deprecate edin; tüketicilere göç yolları gösterin.
• API Gateway ile authentication, rate limiting, caching ve logging merkezi yönetin.

Performans optimizasyonu

• Response size'ı küçültmek için projection, field selection ve gzipping kullanın.
• Cache stratejileri: CDN, edge caching, HTTP cache headers (ETag, Cache‑Control).
• Bulk endpoints ve batch işlemlerle round trip sayısını azaltın.

Güvenlik

• OWASP API Security top 10 rehberine uyun; input validation, authN/authZ ve rate limiting şarttır.
• Secret management ve key rotation politikalarını uygulayın.

Observability

• Trace, metric ve log'u correlate eden bir stack kurun; SLO ve alert'leri tanımlayın.
• Client errors (4xx) ve server errors (5xx) için farklı uyarı seviyeleri belirleyin.

8. SIK YAPILAN HATALAR

• Dokümantasyonu üretimden ayrı tutmak—OpenAPI ile otomatik docs ve örnek istekler sağlayın.
• Hataları insana yönelik değil sadece geliştiriciye yönelik yazmak—müşteri entegrasyonunu düşünün.
• Versiyonlamayı son çare yapmak—planlı versiyonlama ve deprecation süreci kurun.
• Schema migration'larını test etmemek—contract testing ile tüketicileri doğrulayın.

9. GELECEK TRENDLER

1. API Federation ve GraphQL Gateway: Birden fazla servis topolojisini tek sorguda birleştiren çözümler artacak.
2. AI destekli API‑design: Otomatik schema önerileri, contract‑analysis ve impact assessment araçları yaygınlaşacak.
3. gRPC-Web ve HTTP/3 adaptasyonu: Düşük gecikme için yeni protokoller ve tarayıcı dostu çözümler büyüyecek.

EK BÖLÜMLER

Sık Sorulan Sorular (FAQ)

1. 1. REST mi GraphQL mi seçmeliyim?

   İhtiyaca göre. Basit CRUD ve caching avantajları için REST, istemcinin farklı veri ihtiyaçları varsa ve tek uçtan fazla alan çekme gerekiyorsa GraphQL uygundur. Performans veya tip güvenliği kritikse gRPC düşünülebilir.

2. 2. API versiyonlamayı nasıl yönetmeliyim?

   Breaking change'leri minimize edin. Header veya media type versiyonlama daha temiz olsa da pragmatic olarak /v1/ kullanımı yaygındır. Deprecation politikası ve migration rehberi sağlayın.

3. 3. Hata mesajları nasıl yapılandırılmalı?

   Tutarlı bir error schema kullanın, traceId ve detaylı validation hatalarını döndürün. Makineler tarafından parse edilebilir ve insan tarafından anlaşılabilir olmalı.

4. 4. Rate limiting için en iyi yaklaşım nedir?

   Per‑api key ve per‑tenant bazlı token bucket uygulayın; 429 ile Retry‑After header verin. Burst toleransları ve SLA öncelikleri belirleyin.

5. 5. Ödemeler gibi kritik işlemlerde idempotency nasıl sağlanır?

   Idempotency‑Key header ile her isteğe benzersiz anahtar verip sunucuda dedupe mekanizması uygulayın. Transactional outbox ve eventual consistency desenlerini kullanın.

6. 6. API dokümantasyonu için öneriler?

   OpenAPI veya GraphQL SDL kullanın, canlı try‑it console, örnek istek/cevap, SDK generation ve changelog sağlayın.

7. 7. API güvenliği için öncelikli tedbirler nelerdir?

   TLS, OAuth2/OpenID Connect, input validation, rate limiting, WAF ve least privilege ilkeleri en önemli başlangıç noktalarıdır.

8. 8. Asenkron operation'ları nasıl expose etmeliyim?

   202 Accepted + status endpoint veya webhook ile asenkron pattern'leri kullanın. Event schema ve delivery semantics belgelenmeli.

Anahtar Kavramlar

OpenAPI

REST API'ler için spec formatı; dokümantasyon ve contract testing için kullanılır.

Idempotency

Tekrarlı çağrıların yan etkisini engelleyen mekanizma.

Rate limiting

API tüketimini sınırlama ve koruma stratejileri.

Correlation ID

Dağıtık trace için istekleri ilişkilendiren benzersiz kimlik.

SLO

Service Level Objective — ölçülebilir performans hedefleri.

Öğrenme Yol Haritası

1. 0–1 ay: HTTP, REST prensipleri, status code'lar ve JSON/HTTP basics öğrenin; küçük bir REST API tasarlayın.
2. 1–3 ay: OpenAPI ile contract design, authentication (OAuth2), rate limiting ve error handling pratiği yapın.
3. 3–6 ay: GraphQL/gRPC temel kavramlarını öğrenin; performance testing, CI/CD, contract testing ve observability uygulayın.
4. 6–12 ay: API governance, federation, API gateway yönetimi ve production‑grade security/scale pratiklerini uygulayın.