API izleme: yalnızca HTTP 200 değil, JSON yanıtı nasıl kontrol edilir

Kısaca: Bir JSON API, {"status":"error","message":"DB unavailable"} gövdesiyle HTTP 200 döndürebilir - yalnızca status kodunu izleyen monitoring "UP" duyurur. Gerçek API izleme yalnızca HTTP katmanını değil, yanıtın içeriğini de kontrol eder.

Sorun: HTTP 200 != çalışan API

REST API kuralları status kodlarını doğru kullanmayı söyler (200 OK, 4xx client error, 5xx server error). Pratikte:

• Bazı API'ler her zaman 200 döner, hata JSON body'dedir
• Bir API gateway 5xx'i error JSON ile 200'e dönüştürebilir
• Frontend BFF endpoint'leri backend'leri sıkça sarar ve backend başarısız olsa da iletişim gerçekleştiyse 200 döner
• GraphQL endpoint'leri her zaman 200 döner, hatalar errors[] alanındadır

Klasik monitoring perspektifinden (HTTP status kodu) her şey OK. Gerçek istemci perspektifinden API bozuk.

Content matching: anahtar kelimeler

HTTP izlemeye en basit ek keyword match'tir. Yanıtta bulunması gereken bir dize tanımlarsınız - eksikse uyarı.

Health check endpoint örneği:

GET /api/health HTTP/1.1

{
  "status": "ok",
  "checks": {
    "database": "ok",
    "redis": "ok",
    "queue": "ok"
  },
  "version": "1.42.3"
}

Keyword match'i "status":"ok" olarak ayarlayın. DB düşerse ve endpoint "status":"degraded" döndürürse, izleme yakalar.

Negative matching: ne eksik olmalı

Bazen belirli bir dize yanıtta YOK diye kontrol etmek daha faydalıdır:

• "error" - body'de hata
• "maintenance" - beklenmedik maintenance modu
• "deprecated" - API endpoint deprecated oldu
• SQL hata parçaları: "SyntaxError", "undefined", "null pointer" - sızan backend hataları

Gelişmiş assertion'lar - roadmap

Düz metin eşleştirmenin sınırları var. Ciddi API izleme için JSON yapısı üzerinde yapılandırılmış assertion'lar (JSONPath ifadeleri) ve çok adımlı sentetik işlemler (login -> korumalı endpoint -> logout) uygundur.

JSONPath assertion'ları ve çok adımlı sentetik işlemler ePulz.io yol haritasındadır ancak şu anda uygulanmamıştır. Bugün ihtiyacınız varsa, ePulz.io HTTP monitörünü, sonucu bir heartbeat monitörü üzerinden gönderen kendi yardımcı script'inizle birleştirin (hata durumunda sadece heartbeat göndermeyin).

İzlemede authentication

İzlenen endpoint genellikle auth gerektirir. Seçenekler:

• Authorization header'da Bearer token - tipik olarak süre dolmadan long-lived monitoring token (güvenli şekilde saklanmalı)
• Query parametresinde API key - log'larda görünür, tercih edilmez
• HMAC imzası - timestamp + URL + body hash, shared secret ile imzalı. En güvenli.
• mTLS - monitoring tarafında client cert. Dahili API'ler için uygun.

Güvenlik notu: İzleme için minimum izinlerle özel hesap / token oluşturun (read-only health endpoint, admin token değil). Token'ı düzenli rotate edin. Monitoring servisi sızdırırsa, tüm API erişimi sızdırmaz.

Response time SLO

API response time, HTTP kodu kadar önemlidir. 30 s timeout'lu istemci, "API 25 s'de 200 döner" ile "API timeout oldu" arasında fark görmez. UX açısından her ikisi de kötü.

Ayarlayın:

• Hard timeout - 10-15 s sonra monitoring DOWN duyurur
• Soft threshold - 500-2000 ms arası response time = warning (degraded performance)
• Trending alerts - son 24 saatte 95. persentil response time %50 artarsa uyarı

Endpoint başına izleme

Büyük bir API'nin onlarca endpoint'i vardır. Sadece /health'ı izlemeyin - o bile yalan söyleyebilir. 3-5 kritik endpoint belirleyin:

• En çok kullanılan business operasyonları (POST /api/orders, GET /api/dashboard)
• Cache hit için read endpoint (hızlı yanıt)
• DB roundtrip'li write endpoint
• Harici entegrasyon endpoint'i (üçüncü tarafı çağırır - bağımlılık kesintilerini algılar)

Her birini ayrı ayrı izleyin. Olay sırasında API'nin hangi parçasının düştüğünü tam olarak görürsünüz.

Sonuç

API izleme HTTP status koduna indirgenemez. Kaliteli izleme, sadece HTTP istemcisi değil gerçek bir istemciye benzemek için status + content match + response time + endpoint başına granülarite + authentication'ı birleştirir.

Keyword match ile API izleme

Status kodu + içerikte keyword + response time + auth header'lar. Endpoint başına granülarite.

7 gün dene →