"API Çalışmıyor" Cümlesinin Altındaki Gerçekler

Bir gün telefonunuz çalar ve müşteriniz (veya frontend developer arkadaşınız) o meşhur cümleyi kurar: "Hocam, API çalışmıyor."

Çoğu junior developer bu noktada hemen koda dalar, logları karıştırır. Oysa tecrübe şunu gösteriyor: Problemlerin %90'ı teknik değil, iletişimsizlik kaynaklıdır. Geriye kalan %10 ise gerçekten teknik bir bug'dır.

Bu yazıda, bir API entegrasyonu sırasında çıkan sorunları nasıl bir dedektif gibi çözeceğinizi adım adım anlatacağım.

Bölüm 1: İletişim Protokolü

Kod yazmadan önce, "nasıl konuşacağımızı" netleştirmemiz lazım.

Dokümantasyon Okuryazarlığı

REST veya GraphQL fark etmez; dokümantasyonu "tarayarak" değil, "okuyarak" anlayın. Özellikle şu kısımlar hayati önem taşır:

Authentication: Bearer token mi, API Key mi, yoksa HMAC imzalama mı? Genelde hatalar buradan çıkar.
Data Types: "ID" alanı string (GUID) mi yoksa integer mı? JSON payload gönderirken 1 ile "1" arasındaki fark, saatlerinize mal olabilir.

Postman/Insomnia Disiplini

Asla "kafadan" istek atmayın. Ekibinizle paylaşılan bir Postman Collection'ınız olsun.

Environment Variables: URL'leri (localhost, staging, prod) ve token'ları değişkenlere atayın. Hardcoded değerler bir gün mutlaka patlar.
Pre-request Scripts: Token alma (login) işlemini otomatize edin. Her seferinde elle token kopyalamak ameleliktir.

Bölüm 2: Gerçek Debugging Adımları

Sorun yaşandığında şu sırayı takip edin:

1. Manuel Test (Tercihen cURL ile)

Postman harika ama bazen UI bizi yanıltabilir. Terminal candır. Sorunu en yalın haliyle görmek için cURL kullanın:

curl -X POST https://api.example.com/v1/orders \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"product_id": 123, "qty": 1}'

Bu komutun çıktısı, UI'ın maskelediği gerçek hatayı size çat diye söyler.

2. Response Header'ları Okumak

Hata mesajı gövdede (body) olmayabilir.

X-Rate-Limit-Remaining: Belki de kotanız doldu?
Access-Control-Allow-Origin: O meşhur CORS hatası. Backend'de izin verilmemiş bir domainden istek atıyor olabilirsiniz.

3. Webhook Dedektifliği

Eğer dışarıdan size veri geliyorsa (Webhook) ve "gelmiyor" deniyorsa, araya bir "casus" koyun.

ngrok: Localhost'unuzu dünyaya açar. Gelen isteği anlık olarak terminalde görürsünüz.
RequestBin / Webhook.site: Geçici bir URL oluşturur. Karşı tarafa "buna istek at" deyin ve gelen verinin parametrelerini, header'larını çıplak gözle görün.

4. Production Log Stratejisi

Prod ortamında "console.log" çalışmaz (çalışmamalı).

Correlation ID: Her isteğe benzersiz bir ID atayın (otomatik middleware ile). Loglarda bu ID ile arama yaptığınızda, o isteğin tüm yaşam döngüsünü görürsünüz.
Sansür: Loglara asla kredi kartı numarası, şifre veya kullanıcı token'ı basmayın. KVKK ve GDPR affetmez.

Bölüm 3: Sık Karşılaşılan ve Yanlış Anlaşılan Hatalar

401 vs 403:
- 401 Unauthorized: "Kimsin bilmiyorum." (Token yok veya geçersiz).
- 403 Forbidden: "Kim olduğunu biliyorum ama yetkin yok." (Admin sayfasına girmeye çalışan User).
Timeout Ayarı: Varsayılan timeout genelde 30 saniyedir ama bir API isteği 3 saniyeden uzun sürüyorsa mimari bir sorun vardır. Client tarafında timeout'u kısa tutun, kullanıcıyı bekletmeyin (fail fast).
Idempotency: Bir ödeme isteği network hatası yüzünden iki kere giderse ne olur? Müşteriden iki kere mi para çekilir? Idempotency-Key header'ı ile sunucunun "ben bu işlemi daha önce yapmıştım" demesini sağlayın.

Bölüm 4: Çemta Çantası (Toolset)

İşinizi kolaylaştıracak ücretsiz veya uygun fiyatlı araçlar:

İstek Atma: Postman (Klasik), Insomnia (Hafif), Hoppscotch (Tarayıcı tabanlı, kurulumsuz).
Hata Takibi (Monitoring): Sentry (Frontend/Backend hataları için standart), Logtail (SQL benzeri sorgularla log tarama).
Altyapı: Redis (Rate limit ve Caching için), RabbitMQ/Kafka (Yoğun istekleri sıraya sokmak için).

Sonuç: Entegrasyon Checklist'i

Yeni bir servisle entegre olurken şunlara tik atın:

[ ] Dokümanı okudum, auth yöntemini anladım.
[ ] Postman'de "Happy Path" (başarılı senaryo) çalışıyor.
[ ] Hatalı senaryoları (yanlış şifre, eksik parametre) test ettim.
[ ] Timeout ve Retry (tekrar deneme) mekanizmalarım hazır.
[ ] Loglama yapıyorum ama hassas verileri gizliyorum.

API entegrasyonları sabır işidir. "Çalışmıyor" diye bir şey yoktur, "Beklenmedik bir yanıt dönüyor" vardır. O yanıtı bulduğunuz an, çözüm de kendiliğinden gelir.

Eğer şu an içinden çıkamadığınız karmaşık bir ödeme sistemi entegrasyonu veya legacy bir SOAP servisiyle boğuşuyorsanız, belki de bir çift taze göze ihtiyacınız vardır. İletişime geçmekten çekinmeyin!

API Entegrasyonlarında Debugging Sanatı: 400'den 200 OK'e Yolculuk