API'niz 200 dönüyor, izleme panosu yeşil, kimse alarm almıyor. Ama müşteriniz boş bir liste, eksik bir alan ya da yanlış bir fiyatla karşılaşıyor olabilir. Başarılı durum kodu, sunucunun isteği işlediğini söyler; doğru veriyi döndürdüğünü değil.
- Başarılı durum kodu (2xx), yalnızca isteğin sunucu tarafından kabul edildiğini gösterir; yanıtın doğru olduğunu garanti etmez.
- Klasik uptime kontrolü sadece durum koduna baktığı için boş, eksik veya hatalı yanıtları "sağlıklı" sayar.
- Güvenilir API izleme dört şeyi birlikte doğrular: durum kodu, yanıt gövdesi, header değerleri ve yanıt süresi.
Başarılı durum kodu API'nin doğru çalıştığı anlamına gelir mi?
Hayır. HTTP durum kodu, sunucunun isteğe verdiği protokol düzeyindeki cevaptır. 200 OK "isteği aldım ve bir yanıt ürettim" demektir. Üretilen yanıtın içeriği doğru mu, eksiksiz mi, güncel mi; bunu durum kodu söylemez.
Bu fark pratikte önemlidir. Uygulama katmanındaki bir hata yakalanıp sarmalandığında, veritabanı sorgusu boş sonuç döndürdüğünde ya da arkadaki bir servis zaman aşımına uğradığında, API yine de 200 ile cevap verebilir. Sunucu açısından işlem "başarılıdır", müşteri açısından ise sistem bozuktur.
Başarılı durum kodu dönerken veri neden yanlış olabilir?
Sahada en sık karşılaşılan dört senaryo şunlardır:
Boş yanıt gövdesi
Sorgu hata vermeden çalışır ama sonuç döndürmez. API 200 ile boş bir liste veya boş bir nesne gönderir.
Eksik veya yanlış alan
Bir sürüm güncellemesi sonrası kritik bir alan kaybolur ya da adı değişir. İstemci uygulama bu alanı bulamaz.
Eski veri (önbellek)
Önbellek katmanı takılı kalır ve güncel olmayan veriyi başarılı bir yanıtla sunmaya devam eder.
Sarmalanmış hata
Arkadaki servis çöker, ancak ağ geçidi veya uygulama hatayı 200 ile gövdenin içinde döndürür.
Dördüncü senaryo özellikle sinsidir. Aşağıdaki yanıtın durum kodu başarılıdır, ama içerik bir hata bildirir:
HTTP/1.1 200 OK
Content-Type: application/json
{
"durum": "hata",
"mesaj": "Stok servisine ulaşılamadı",
"urunler": []
}
Klasik uptime kontrolü bu hatayı neden yakalayamaz?
Klasik uptime izleme tek bir soruyu sorar: "Sunucu cevap verdi mi?" Cevap 200 ise kontrol başarılı sayılır. Yanıtın içine bakmadığı için yukarıdaki gibi bir durumda panoda her şey yeşil görünür, sorunu ise ilk olarak müşteri fark eder.
Yanıtı doğrulayan izleme ile
- Boş veya hatalı gövde anında alarm üretir
- Kritik alanların varlığı ve değeri her kontrolde test edilir
- Sorunu müşteriden önce siz öğrenirsiniz
Yalnızca durum koduna bakan izleme ile
- 200 dönen hatalı yanıt "sağlıklı" sayılır
- Sorun şikâyet veya destek talebiyle ortaya çıkar
- Hatanın başlangıç zamanı belirsiz kalır
Başarılı durum kodunun ötesinde hangi doğrulamalar gerekir?
Bir API yanıtının gerçekten sağlıklı olduğunu söyleyebilmek için dört katmanı birlikte kontrol etmek gerekir:
| Doğrulama | Neyi kontrol eder? | Yakaladığı sorun |
|---|---|---|
| Durum kodu | Beklenen kod dönüyor mu? (200, 201 vb.) | Sunucu ve yönlendirme hataları |
| Yanıt gövdesi | JSON veya XML içindeki kritik alanlar mevcut ve doğru mu? | Boş, eksik veya hatalı veri |
| Header değerleri | Beklenen başlıklar dönüyor mu? | Yanlış içerik tipi, önbellek ve güvenlik başlığı sapmaları |
| Yanıt süresi | Belirlediğiniz eşiğin altında mı? | Yavaşlama ve zaman aşımı riski |
Bu dört kontrol birbirini tamamlar. Durum kodu doğru olup gövde yanlışsa gövde doğrulaması, gövde doğru olup yanıt 8 saniyede geliyorsa süre eşiği alarm üretir.
Hangi durum kodları başarılı sayılmalı?
"Başarılı durum kodu" denince akla genellikle 200 gelir, oysa 2xx ailesinin her üyesi farklı bir anlam taşır. İzleme kuralını yazarken endpoint'in gerçekte hangi kodu döndürmesi gerektiğini bilmek gerekir.
| Kod | Anlamı | İzlemede dikkat edilecek nokta |
|---|---|---|
200 OK | İstek başarılı, yanıt gövdesi var | Gövde içeriğini mutlaka doğrulayın |
201 Created | Yeni kaynak oluşturuldu | Yanıttaki kaynak kimliğini ve konum başlığını kontrol edin |
202 Accepted | İstek kabul edildi, işlem henüz bitmedi | İşlemin gerçekten tamamlandığı ayrıca doğrulanmalıdır |
204 No Content | Başarılı, gövde yok | Gövde beklemeyin; durum kodu ve header yeterlidir |
Her endpoint için tek bir kodu "doğru" kabul etmek yanlış alarma yol açar. Bir POST endpoint'inin 201, bir DELETE endpoint'inin 204 döndürmesi normaldir. Beklenen kodu endpoint bazında tanımlayın.
API izleme ile yanıt doğrulaması nasıl kurulur?
Endpoint ve beklenen durum kodunu tanımlayın
İzlenecek adresi ve metodu girin, ardından bu endpoint'ten beklediğiniz başarılı durum kodunu seçin.
Yanıt gövdesi için kritik alanları belirleyin
JSON veya XML içinde mutlaka bulunması gereken alanları ve bu alanların beklenen değerlerini ekleyin.
Header ve süre eşiğini ekleyin
Dönmesi gereken başlıkları ve kabul edeceğiniz en yüksek yanıt süresini belirleyin.
Alarm kanallarını bağlayın
Kurallardan biri bozulduğunda bildirimin e-posta, Webhook, Slack veya Telegram üzerinden ekibe ulaşmasını sağlayın.
Gövde doğrulamasında tüm yanıtı birebir karşılaştırmak yerine iş açısından kritik birkaç alanı seçin. Örneğin durum alanının basarili olması ve urunler listesinin boş olmaması çoğu zaman yeterlidir. Bu yaklaşım, zamanla değişen alanlardan kaynaklanan gereksiz alarmları azaltır.
API'nizin içini de izleyin
Durum kodunun yanında yanıt gövdesini, header'ları ve süreyi her kontrolde doğrulayın.
Sıkça sorulan sorular
API 200 dönüyorsa neden hatalı olabilir?
Çünkü 200, sunucunun isteği işleyip bir yanıt ürettiğini gösterir. Yanıtın içeriği boş, eksik veya hatalı olsa da durum kodu başarılı kalabilir. Bu yüzden içerik ayrıca doğrulanmalıdır.
Başarılı durum kodu hangi aralıktadır?
2xx aralığındaki kodlar başarılı kabul edilir. En yaygın olanlar 200 (OK), 201 (Created), 202 (Accepted) ve 204 (No Content) kodlarıdır.
Yanıt gövdesi doğrulaması neleri kontrol eder?
JSON veya XML içindeki kritik alanların varlığını ve beklenen değerlerini kontrol eder. Böylece boş liste, eksik alan veya gövdeye gömülü hata mesajı gibi durumlar yakalanır.
Uptime izleme ile API izleme arasındaki fark nedir?
Uptime izleme genellikle adresin cevap verip vermediğine bakar. API izleme ise cevabın içeriğini, header değerlerini ve yanıt süresini de doğrulayarak verinin doğru olup olmadığını kontrol eder.
Her API için aynı durum kodunu beklemek doğru mudur?
Hayır. Bir endpoint'in beklenen kodu metoduna ve işlevine göre değişir. Oluşturma işlemi 201, silme işlemi 204 döndürebilir. Beklenen kodu endpoint bazında tanımlamak gerekir.
Sonuç
Başarılı durum kodu, bir API'nin sağlıklı olduğunu kanıtlamaz; yalnızca sunucunun cevap verdiğini gösterir. Müşteriniz yanlış veriyle karşılaşmadan önce sorunu yakalamak için durum kodunu, yanıt gövdesini, header değerlerini ve yanıt süresini birlikte doğrulayan bir izleme kurgusuna ihtiyacınız var. Kurallardan biri bozulduğunda alarm doğrudan ekibinize ulaşır.
