API izleme

Neden API'nin kendi izlemeye ihtiyacı var?

API sadece /api/ altında bir sayfa değildir. Bir kontrattır. HTTP yöntemi önemlidir - GET ile POST arasında semantik farklılık vardır. Başlıklar yetkilendirme, içerik pazarlığı, idempotent anahtarları taşır. İstek gövdesi girdidir. Yanıt kodu önemlidir (401 ile 403 ile 422 - her biri farklı bir hikaye anlatır). Yanıt gövdesinin bir yapısı vardır - entegratörlerin güvendiği JSON yolları. Sadece GET ile URL'ye giden sıradan bir uptime kontrolü API'nin çökebileceği çoğu yöntemi kaçırır: 200 döndürmeye devam eden geçersiz JSON, hatalı verileri kabul eden yetkilendirme endpoint'i, bozuk payload şemasıyla gelen webhook, 200 dönen ama içinde "status": "error" olan endpoint.

API izleme bunu çözer; isteğin ve yanıt doğrulamasının her parçası üzerinde kontrol sahibi olmanı sağlar. Entegratörlerinin yaptığı çağrının birebir aynısını yapılandırırsın - aynı yöntem, aynı başlıklar, aynı gövde, aynı yetkilendirme - ve başarının ne anlama geldiğini tam olarak belirlersin - kesin kodlar, JSON yollarındaki değerler, yanıt süresi eşikleri, boyut sınırları.

İstek yapılandırması

DiagnoSEO Uptime Monitoring üzerindeki her API izleyici için şu ayarları yapabilirsin:

• HTTP yöntemi: GET, POST, PUT, PATCH, DELETE, HEAD. Entegratörlerin kullandığı yöntemi seç.
• Özel başlıklar: JSON nesnesi olarak, ör. {"Authorization": "Bearer eyJ...", "X-API-Version": "2024-01-15"}. OAuth, JWT, API anahtarları, içerik pazarlığı testleri için standart yöntem.
• İstek gövdesi: Herhangi bir string - JSON, XML, form-encoded, düz metin. POST/PUT/PATCH/DELETE işlemlerinde gönderilir.
• Basic auth: Endpoint bu şekilde korunuyorsa kullanıcı ve şifre gir.
• Beklenen durum kodları: Liste veya aralık. Varsayılan 200-399'dur fakat tek bir kodla sınırlandırabilirsin (ör. create endpoint'i için tam olarak 201 gibi) ya da belirli kodlara izin verebilirsin (ör. 200,202,204).

Kontrol maksimum 5 yönlendirmeyi takip eder, gzip çözer, JSON olup olmadığını tespit etmek için Content-Type analiz eder. Her kontrol gerçek kodu, yanıt süresini, boyutunu ve olası hatayı kaydeder. Birden fazla ardışık hata (ayar yapılabilir, varsayılan 2) bir olayı tetikler.

JSON path doğrulamaları

Yalnızca durum kodları birçok API için yeterli değildir. Sağlık endpoint'i 200 dönebilir ama gövdesi {"status": "degraded", "db": "down"} olabilir - yine de kesinlikle bunu bilmek istersin. Fiyat API'si, gövdesinde data.price null olmuş şekilde 200 dönebilir. Arama motoru API'si, indeks çöktüğünde 200 de dönebilir ama results: [] ile.

Böyle durumlar için, JSON path doğrulaması yapılandır. Yolu belirt (ör. data.status ya da health.checks.db) ve beklenen değeri gir (ör. healthy, true veya belirli bir sayı). Her kontrol sırasında yanıt JSON olarak çözülür ve belirtilen yol altındaki değer karşılaştırılır. Uyuşmazlık, HTTP durumundan bağımsız olarak kontrolü hatayla bitirir.

Yolun söz dizimi, noktasyon ve köşeli parantezli şekildedir: data.items[0].id çalışır, users.john.email de aynı şekilde. Doğrulanan değer string olarak karşılaştırılır; bu nedenle "true" bool true ile, sayılar hem string hem sayı olarak eşleşir.

Kimlik doğrulama desenleri

En yaygın iki kimlik doğrulama stili kutudan çıkar çıkmaz desteklenir. Bearer tokenları (OAuth, JWT, API key'leri) için headers alanı kullan: {"Authorization": "Bearer eyJhbGciOi..."}. Token izleyicide tutulur ve her kontrolde gönderilir. Basic auth için kullanıcı adı/şifre özel alanını kullan - bunlar saklanır ve standart başlıkta birleştirilir.

Eğer kimlik doğrulama her istek için imza atılması veya token yenileme gerektiriyorsa iş biraz daha zordur. İki makul desen: (1) izleme için özel olarak uzun ömürlü bir servis hesabı token'ı yapılandır, veya (2) gerçek korumalı endpoint'in durumunu yansıtan, oturum açmaya gerek olmayan bir health endpoint açıp onu izle. Çoğu modern API'de bu zaten hazırdır.

Önerdiğimiz desenler

• Kritik bir endpoint için bir izleyici. Her birini test etme - gerçek zarar verecek 5-10 taneyi seç.
• Doğru durum kodlarını kullan. Varsayılan 200-399 API'ler için fazla esnektir. Oluşturma endpoint'i tam olarak 201 döndürmelidir; idempotent endpoint tam olarak 200; oturum açma endpoint'i tam olarak 200 (başarı) veya 401 (iyi yapılandırılmış hata - 500 değil).
• Durumu JSON doğrulaması ile birleştir. Birlikte hem iletim hem içerik katmanındaki gerilemeleri yakalar. Yalnızca durum kodu içerik hatasını yakalayamaz; tek başına JSON doğrulama yönlendirmede kırılgan olur.
• Yanıt süresi eşiği ayarla. API yavaşlaması, bağımlılıklardaki sorunların öncü göstergesidir. rt_threshold_ms = 800 olan bir izleyici, API'nin çökmeden önce yavaşladığını gösterir.
• Gövdeyi küçük tut. Kontrol her dakika yapılır - büyük gövdeler iki tarafta da bant genişliğini boşa harcar. Temsili-ama-minimal payload'lar yeterlidir.

Diğer izleme türleriyle birleştir

Her API endpoint'i için API izleyici çağrının çalıştığını doğrular. Ayrı bir ping veya port izleyici hostun erişilebilirliğini doğrular. Aynı host adında yapılan SSL/alan kontrolü sertifika ve kayıt sorunlarını yakalar. Alt-izleyici DNS, olası kayıt değişikliklerini izler. Dört izleyicinin birleşimiyle API üzerinde tam bir görünürlük elde edilir ve asgari çakışma sağlanır.

Yapılandırma

Aracı aç, "İzleyici ekle"ye tıkla, "API" tipini seç. URL'yi yapıştır. Gelişmiş bölümünü aç. Yöntemi seç, başlıkları JSON olarak yapıştır, gerekiyorsa body'yi gir, basic auth gerekiyorsa kullan, beklenen kodları yaz (ör. 200 veya 200,201). Uygunsa JSON path doğrulaması ekle. Aralık ve onay eşiği ayarla. Kaydet. Sonraki döngüde izleyici API'ne tam bir entegratör gibi istek yapar, yanıtı doğrular ve regresyon anında uyarır.

Sıkça Sorulan Sorular

• API izleme için hangi HTTP yöntemlerini kullanabilirim?

  GET, POST, PUT, DELETE, PATCH ve HEAD. Yöntemi her bir izleyici için yapılandır — write endpoint'leri için (POST/PUT/PATCH) istek gövdesi JSON string veya form verisi olarak da yapılandırılabilir.

• JSON doğrulamaları nasıl çalışır?

  Bir JSON yolu (ör. data.status veya results[0].id) ve beklenen bir değer girersin. İzleyici yanıtı alır, JSON olarak çözer, yolu çıkarır ve beklenenle karşılaştırır. Uyuşmazlık varsa "assertion failed" hatasıyla ve gerçek değeri göstererek kontrol başarısız olur.

• Kimlik doğrulama başlıklarını gönderebilir miyim?

  Evet. Özel HTTP başlıkları izleyici başına yapılandırılabilir — Authorization tokenları, API anahtarları, content-type, istediğiniz her şey. Başlık değerleri veri tabanında şifrelenmiş olarak saklanır. Basic Auth için otomatik olarak isteğe imza atan özel kullanıcı adı/şifre alanı bulunur.

• API'm 200 ile hata payload'ı dönerse ne olur?

  Yaygın bir desen: API HTTP 200 döner ama body şunu içerir: {"status":"error"}. Basit bir uptime izleyici burada bir sorun olduğunu anlamaz. JSON doğrulaması status == "ok" kullanarak bu hatayı yakalayabilirsin — doğrulama başarısız olur ve HTTP 200 dönse de izleyici DURUMU KAPALI olarak raporlar.

• Rate limit olan API'yi nasıl izlerim?

  Kontrol aralığını API limitine göre ayarla (ör. API saatte 12 çağrı izin veriyorsa 5 dakikalık aralık). İzleyici her bir kontrol için her bir bölgeden bir API çağrısı yapar. Çok bölgeli kontroller toplam çağrı sayısını artırır — API'niz için sıkı limitler varsa tek bölgeli kontrol kullanın.