API Nedir, Ne İşe Yarar?

Geliştiricilerin diller, çerçeveler ve platformlar arasında köprü kurmasını sağlayan en temel araçlardan biri API’dir. “Uygulama Programlama Arayüzü” anlamına gelen API, bir yazılım bileşeninin başka bir bileşenle nasıl konuşacağını ayrıntılı biçimde tarif eden bir sözleşme gibidir. Bu sözleşme; hangi isteğin nasıl yapılacağını, hangi verinin dönüleceğini, hataların nasıl bildirileceğini, güvenliğin nasıl sağlanacağını ve sürümlerin nasıl yönetileceğini belirler. Kısacası API, modern yazılım ekosisteminin trafikteki kavşaklarıdır: Akışı düzenler, kuralları koyar ve her şeyin çarpışmadan ilerlemesini sağlar.

API Nedir?

API, yazılımlar arası iletişimi belirlenmiş kurallar çerçevesinde standartlaştıran bir arayüzdür. Bir taraf “stemci (client), diğer taraf  sunucu (server) rolünü üstlense de bu roller değişebilir; önemli olan, arada API’nin tanımladığı istenebilirlik (hangi işlemler yapılabilir), söz dizimi (istek nasıl yapılandırılır) ve anlambilim (isteğin anlamı nedir, hangi etkileri vardır) bütünüdür.

API’yi bir restorandaki garsona benzetmek sık kullanılan bir anlatımdır: Menü (dokümantasyon) üzerinden sipariş (istek) verirsiniz; garson (API), mutfakla (iş mantığı, veri kaynakları) konuşur; sonucunda tabak (yanıt) masanıza gelir. Garsonun görevi mutfağın içini ifşa etmeden sizinle ve mutfakla doğru dili konuşmaktır. Yazılım dünyasında bu, iç mimarinin saklanması (encapsulation), sınırların belirgin olması (bounded context) ve dış dünyaya yalnızca gerekli işlevlerin açılması anlamına gelir.

API’ler sadece web ile sınırlı değildir: İşletim sistemi API’leri, donanım sürücüleri, kütüphane/SDK arayüzleri de aynı ilkelerle çalışır. Ancak günümüzde bulut ve mikro servis mimarilerinin yaygınlaşmasıyla Web API’ler (HTTP/HTTPS üzerinden JSON veya XML yanıtlar dönen uç noktalar) pratikte en görünür hale gelmiştir.

API’nin Çalışma Prensibi: Nasıl İşler?

API’lerin çalışma biçimini üç temel katmanda düşünebiliriz:

Sözleşme Katmanı (Contract)
Bu katman, dış dünyaya şu soruların yanıtını verir:

• Hangi uç noktalar (endpoint) mevcut?
• Hangi yöntemlerle (GET, POST, PUT, DELETE, PATCH) çağrılır?
• İstek gövdesi (body) ve parametreler nasıl olmalıdır?
• “Yanıt şeması nedir, hata kodları nasıl döner?”

Bu sözleşme, çoğu zaman OpenAPI/Swagger gibi şemalarla veya GraphQL şeması ile makinece de anlaşılabilir biçimde yayınlanır.

Uygulama Mantığı Katmanı (Application/Domain Logic)
İstek kabul edildikten sonra devreye iş kuralları girer. Veritabanından okuma/yazma, üçüncü taraf servislerle konuşma, doğrulama, iş akışları, kuyruklar, önbellekler bu katmanda yer alır. İstemci bu ayrıntıları bilmez; API, bu mantığı uygun biçimde soyutlayıp çıktıyı standart bir yanıt haline getirir.

Altyapı Katmanı (Infrastructure)
Kimlik doğrulama (OAuth2, API key, JWT), yetkilendirme (RBAC/ABAC), hız limiti (rate limit), kota, CORS, TLS/SSL, yük dengeleme, gözlemlenebilirlik (log, metrik, iz sürme/tracing) gibi konular bu katmanda ele alınır. Sağlam bir API, bu altyapısal korumalar ve görünürlük araçları olmadan üretimde uzun süre ayakta kalamaz.

İstek-Yanıt Döngüsü tipik olarak şöyle ilerler:

• İstemci belirli bir URI’ye HTTP isteği atar.

• API katmanı, kimlik doğrulama ve doğrulama adımlarını uygular.

• İş mantığı istenen veriyi hazırlar; gerekiyorsa başka API’lerle konuşur.

• Yanıt, belirlenen şemaya uygun şekilde (çoğunlukla JSON) döndürülür; hata durumunda tutarlı bir hata formatı ve uygun HTTP durum kodu (4xx/5xx) verilir.

Bu akışın verimli olması için önbellekleme (caching), ETag/If-None-Match gibi koşullu istekler, idempotent işlemler (aynı isteğin tekrarı aynı sonucu verir), pagination (limit/offset veya cursor-based), sürümleme, geriye dönük uyumluluk ve dokümantasyon kritik önemdedir.

API Türleri: REST, SOAP, GraphQL ve Diğerleri

“api türleri” dendiğinde aslında birkaç farklı sınıflamadan bahsedebiliriz: mimari stil/protokol bazlı ve erişim modeli bazlı.

Mimari Stil / Protokol Bazlı

• REST (Representational State Transfer)
  Bir protokolden ziyade mimari ilkeler bütünüdür. HTTP’nin olanaklarını (kaynak odaklı URI’lar, stateless yapı, standard HTTP metodları ve durum kodları, cache semantikleri) verimli kullanmayı hedefler. Yaygın olarak JSON kullanılsa da REST bunu zorunlu kılmaz. Artıları: Basitlik, yaygın ekosistem, tarayıcı/dil bağımsızlığı. Zorlukları: Fazla veya eksik veri çekme (over/under-fetching), çok endpoint yönetme, karmaşık ilişkilerde “n+1 istek” paterni.

• SOAP (Simple Object Access Protocol)
  XML tabanlı, katı bir zarf yapısıyla (envelope) geleneksel kurumsal dünyada yaygınlaşmış bir protokoldür. Sözleşme genelde WSDL ile tanımlanır. Artıları: Tip güvenliği, standartlaşmış güvenlik ve işlem semantiği (WS-Security, WS-AtomicTransaction). Zorlukları: Ağırlık, esneklik kısıtları, modern web-mobile senaryolarında hantallık.

• GraphQL
  İstemcinin tam olarak ihtiyaç duyduğu alanları tek bir sorguda ifade ettiği, güçlü tip sistemine sahip bir sorgulama dilidir. Over/under-fetching sorunlarını azaltır, ilişkisel verileri tek sorguda çekebilir, şema üzerinden geliştirme deneyimini zenginleştirir. Artıları: Esnek sorgular, şema odaklı geliştirme, güçlü araçlar. Zorlukları: N+1 sorgu riski (çözüm: data loader), caching semantiklerinin REST kadar doğal olmaması, yetkilendirme/limitlendirme dikkat ister.

• gRPC (HTTP/2 + Protobuf)
  Google’ın geliştirdiği, özellikle servis-servis (microservice) iletişiminde yüksek performanslı, ikili (binary) protokol kullanan bir yaklaşımdır. Streaming (client/server/bidirectional) destekler. Artıları: Düşük gecikme, güçlü tip güvenliği, verimlilik. Zorlukları: Tarayıcı desteği sınırlı (genelde proxy gerekir), insan tarafından okunabilirlik düşüktür.

• Webhooks & Event-Driven API’ler
  “Ben sormadan bana haber ver” yaklaşımıdır. Bir olay olduğunda sağlayıcı sizin belirlediğiniz URL’ye POST atar. Ödeme bildirimleri, Git push olayları, CRM tetikleyicileri vb. için idealdir. Zorlukları: Güvenlik (imza doğrulama), tekrar teslim (at-least-once semantics), sıralama ve idempotency.

• WebSocket / SSE
  Gerçek zamanlı, çift yönlü (WebSocket) ya da tek yönlü yayın (Server-Sent Events) için uygundur. Canlı skor, sohbet, izleme panoları gibi alanlarda tercih edilir.

• AsyncAPI (belirtim)
  MQTT, Kafka, AMQP gibi mesajlaşma protokollerini tanımlamak için kullanılan şema standardıdır. Olay güdümlü mimarilerde OpenAPI’nin asenkron karşılığı gibi düşünülebilir.

Erişim Modeli Bazlı

• Public (Açık) API: Geniş geliştirici kitlesine açık; genelde anahtar veya OAuth ile erişilir.

• Partner API: Yalnızca iş ortaklarına sunulan, SLA’leri tanımlı arayüzler.

• Private (İç) API: Kurum içindeki ekipler/servisler arasında kullanılır; dışa kapalıdır.

• Composite API: Birden fazla kaynağın tek çağrıda birleştirilmesi (BFF – Backend For Frontend, aggregator paternleri).

“Apı türleri” ifadesi bu nedenle hem protokol/mimari hem de erişim modelini kapsar; seçim, ihtiyaç ve kısıtlar üzerinden yapılmalıdır.

API’ler ve Web Geliştirme: Web Uygulamalarıyla Entegrasyon

Günümüz web’inde ön yüz (React/Vue/Next/Nuxt), arka yüz (Node/Express, .NET, Java/Spring, Python/FastAPI, Go/Gin), mobil (iOS/Android/Flutter) ve hatta IoT cihazları, hepsi API’lerle konuşur. Entegrasyonun belkemiği şu ilkelerle sağlıklı kurulur:

1. Temiz Sınırlar ve BFF (Backend For Frontend)
   Farklı istemci türleri (web, mobil, dahili panel) için tek bir “genel amaçlı” API bazen hantal olabilir. BFF yaklaşımı, her istemciye özgü ihtiyaçları optimize eden ince bir arka katman sunar. Böylece mobilin veri ihtiyacı ile web’in ihtiyacı ayrıştırılır; gereksiz veri taşınmaz.

2. Sözleşmeye Dayalı Geliştirme (Contract-First)
   Önceden iyi tanımlanmış bir OpenAPI/GraphQL şemasıyla hem istemci hem sunucu paralel geliştirilebilir. Mock sunucularla UI ekipleri gerçek API hazır olmadan çalışmaya başlar; hatalar erken yakalanır.

3. Güvenlik ve CORS
   Tarayıcı tabanlı isteklerde CORS politikası önemlidir. Token ve cookie stratejisi, XSS/CSRF korumaları, HTTPS zorunluluğu, anahtarların istemciye sızmaması (ör. yalnızca backend’te saklama) gibi konular net olmalıdır.

4. Hata Formatı ve Gözlemlenebilirlik
   Tek tip hata zarfı ve merkezi log/metric/trace (ELK/EFK, OpenTelemetry, Prometheus/Grafana) olmadan ölçekli entegrasyonların bakımı zorlaşır. Her çağrı için correlation/trace id üretmek, sorun çözmeyi dramatik biçimde hızlandırır.

5. Performans ve Önbellek
   CDN ve reverse proxy (ETag, Cache-Control), sayfalama, istek birleştirme (batching), alan seçimi (sparse fieldsets) ve GraphQL’de query cost/complexity limitleri, kullanıcı deneyimini doğrudan etkiler.

API Kullanmanın Avantajları ve Dezavantajları

Avantajlar

• Hız ve Yeniden Kullanım: Aynı işlevin tekrar tekrar yazılması gerekmez; “parçala-yönet-yeniden kullan” kültürü gelişir.

• Ekosistemleşme: Dışa açılan API’ler etrafında entegrasyonlar, uygulamalar, pazar yerleri oluşur.

• Esneklik: İç mimari özgürce evrilebilir; API sözleşmesi korunduğu sürece istemciler etkilenmez.

• Ölçeklenebilirlik: Mikro servisler ve olay güdümlü mimarilerle birlikte, farklı bileşenler bağımsızca ölçeklenir.

• Güvenlik ve Soyutlama: Hassas veriye doğrudan erişim yerine, kontrollü, loglanan ve yetkilendirilen kapılar sunulur.

Dezavantajlar / Dikkat Edilmesi Gerekenler

• Bağımlılık ve SLA Riski: Üçüncü taraf API’ye bağımlılık; kotaya takılma, versiyon kırılması, servis kesintisi gibi riskler getirir.

• Gecikme ve Maliyet: Aşırı ağ çağrısı yüksek gecikme ve altyapı maliyeti doğurur.

• Güvenlik Açıkları: “OWASP API Security Top 10” ihlalleri (kırık yetkilendirme, aşırı veri maruziyeti vb.) ciddi sonuçlar doğurabilir.

• Sürümleme ve Yaşam Döngüsü Yönetimi: Versiyon artışı, geriye dönük uyumluluk, kullanım dışı bırakma (deprecation) süreci iyi yönetilmezse ekibin hızı düşer.

• Test ve Gözlemlenebilirlik: Yetersiz test ve izlenebilirlik, arıza anında kök neden analizini zorlaştırır.

Bir API Nasıl Tasarlanır ve Geliştirilir?

Bu bölüm, “Apı” tasarlarken pratik bir yol haritası sunar. “Apı nedir” sorusunu aştıktan sonra nasıl iyi API yazılır sorusu asıl sınavdır.

1) Amaç, Kitle ve Kullanım Senaryoları

• Kullanıcı Profili: İç ekip mi, partner mi, herkese açık mı?

• Kullanım Biçimi: Yüksek hacimli okuma (read-heavy) mı, işlem yoğun (write-heavy) mi?

• SLI/SLO/SLA: Hedef gecikme, hata oranı, kullanılabilirlik; beklenti baştan net olmalı.

2) Sözleşme Tasarımı (Contract Design)

• Kaynak Modeli (REST): Kaynakların URI hiyerarşisi ve eylemler.

• Şema: OpenAPI 3.1 ile istek/yanıt şemaları, enum’lar, birim/format (ISO 8601 tarih, RFC 8259 JSON).

• GraphQL Şeması: Tipler, sorgular, mutasyonlar, abonelikler; n+1 tuzağına karşı dataloader.

• gRPC Proto: Mesaj tanımları, servis arayüzleri, streaming kararları.

3) Güvenlik

• Kimlik Doğrulama: OAuth2/OpenID Connect, servis-servis için mTLS veya signed token.

• Yetkilendirme: RBAC/ABAC, kapsamlar (scopes), nesne düzeyi kontroller (object-level auth).

• Girdi Doğrulama: Şema validasyonu, whitelist yaklaşımı, boyut sınırları.

• Ortak Zayıflıklar: Rate limit, bot koruması, imzalı webhooks, gizli bilgilerin (secrets) yönetimi.

• Günlükleme: PII içermeyen, sahtecilik analitiğine elverişli log yapısı.

4) Hata Yönetimi ve Durum Kodları

• Doğru HTTP kodları: 200/201/204, 400/401/403/404/409/422, 429, 500/503.

• İdempotency-Key desteği: Ağ hatasında yinelenen işlemlerin güvenli olması.

5) Sürümleme (Versioning) ve Uyumluluk

• URI tabanlı veya header tabanlı versiyonlama.

• “Breaking change” öncesi deprecation duyuruları, geçiş penceresi, çift yazma/okuma stratejileri.

• Şema evrimi: Yeni alanları opsiyonel başlat, eski alanları bir süre destekle.

6) Performans, Ölçeklenebilirlik ve Dayanıklılık

• Pagination: Offset/limit yerine cursor-based sayfalama tercih edilebilir.

• Filtreleme/Sıralama/Alan Seçimi:

• Önbellek: CDN, reverse proxy, ETag/Last-Modified, cache-aside stratejileri.

• Toplu İşlemler: Batch endpoints veya GraphQL’de tek sorguda çok alan.

• Dayanıklılık: Circuit breaker, retry-backoff, timeouts, bulkhead isolation.

7) Dokümantasyon, SDK ve Geliştirici Deneyimi (DX)

• API Portal: Açık, arama yapılabilir, versiyonlu dokümanlar; “try it” alanları.

• Örnekler: Dil bazlı snippet’ler (JS/Python/Java/Go), Postman koleksiyonları, Curl örnekleri.

• SDK/Client: Otomatik üretilmiş (OpenAPI codegen) veya el yazımı istemci kütüphaneler.

• Değişiklik Günlüğü (Changelog): Kırıcı değişiklikler için net rehber.

8) Test, CI/CD ve Gözlemlenebilirlik

• Sözleşme Testleri: Contract-first ise mock ve tüketici odaklı sözleşme testleri (Pact).

• Entegrasyon ve E2E: Gerçek veriyle, staging ortamında.

• Performans Testi: K6/JMeter ile yük, gecikme, bozulma noktaları.

• CI/CD: Otomatik şema doğrulama, migration yönetimi, kanarya/blue-green dağıtımlar.

• Observability: Dağıtık iz sürme (OpenTelemetry), metrik/alert (Prometheus/Grafana), merkezi log.

9) Fiyatlandırma, Kota ve Governance (Açık/Partner API’ler için)

• Planlar: Ücretsiz katman, ücretli katmanlar, adil kullanım kotası.

• Rate Limit & Quota: Yanıt header’larında kalan limitleri göster.

• Anahtar Döngüsü: Anahtar oluşturma/yenileme/iptal, dar kapsamlı (least privilege) yetkiler.

• Uyum ve Denetim: KVKK/GDPR, denetim izleri, veri yerelleştirme, sözleşmeler.

10) Uygulamalı Örnek: Basit Sipariş API’si İçin Kritik Tasarım Kararları

• Kaynaklar: /orders, /orders/{id}, /orders/{id}/items

• Kimlik Doğrulama: OAuth2 client-credentials (servis-servis) + JWT

• İş Kuralları: “Shipped” olan sipariş güncellenemez (409 döndür).

• Sayfalama: Cursor: ?cursor=eyJpZCI6IjEyMyJ9&limit=50

• Hata: 422 doğrulama; 409 iş kuralı çakışması; 401/403 erişim.

• Versiyon: /v1/ ile başla; gelecekte /v2/ introdukesi için deprecation planı hazırla.

• Gözlem: Her istek-yanıta Trace-Id ekle; 1 saniyeyi aşan istekleri “slowlog”a yaz.

Diğer blog yazılarımıza buradan ulaşabilirsiniz.