UptimeScout incidents yanıtına bakarak bir hizmette hemen kesinti olduğunu ilan edebilir miyiz? Hayır: bu uç nokta, yakın zamanda ihlal sinyalleri yükselen hizmetleri listeler ve spesifikasyon bunların sağlayıcı tarafından doğrulanmış olaylar olmadığını açıkça belirtir. Pratikte elde edilen, kesintinin nedeni hakkında hazır bir sonuç değil, kontrol edilmesi gereken kısa bir sinyal listesidir.

Bu ayrım, nöbetçi mühendis ve analist için önemlidir: otomatik bir uyarı, olguyu doğrulamayı ve nedenini açıklamayı sağlayıcının resmî durum bilgisine ya da kendi teşhis çalışmalarınıza bırakarak “Y bölgesindeki X hizmetini kontrol edin” diyebilir. UptimeScout spesifikasyonu, sinyaller, mevcut durum ve gözlem geçmişi için ayrı uç noktaları belgeliyor.
Sinyal listesi tam olarak ne döndürür?
/v1/incidents, ihlal sinyalleri yükselmiş hizmetlerden oluşan bir kataloğa yönelik GET uç noktasıdır. Parametreleri arasında hizmet, bölge, kategori, arama sorgusu ve zaman aralığı filtreleri bulunur. Yanıt için lisans gerekir; API, Bearer belirteciyle kimlik doğrulamayı tanımlar. Bölge alanı iki harfli bir kod kabul eder; hours ise 1 ile 2160 saat arasındaki bir aralığı belirler.
Yoldaki “incident” sözcüğünü “doğrulanmış kesinti” diye yorumlamak kolaydır; ancak dokümantasyon daha dar bir anlam tanımlar: güncel bir gözlem sinyali. Bu nedenle bildirim, yanıttaki verilere uygun biçimde, örneğin “erişilebilirlik ihlali sinyali alındı” şeklinde yazılmalı; hizmet sağlayıcısının olayı kabul ettiği ileri sürülmemelidir.
Bildirimden önce yapılacak asgari kontroller
Önce özgün yanıtı, alındığı zaman ve istek parametreleriyle birlikte kaydedin. Ardından dönen hizmeti ve bölgeyi kontrol edin; hizmetin observed_at ve stale alanlarına bakarak verinin güncelliğini değerlendirin. Gözlem eski olarak işaretlenmişse, bunu güncel sinyalden ayırın ve “şu anda” geçerli bir durum gibi göstermeyin.
curl -sS 'https://api.uptimescout.com/v1/incidents?region=US&hours=24' \
-H "Authorization: Bearer $UPTIMESCOUT_LICENSE_KEY"
Bu, ABD için 24 saatlik aralıkla yapılan bir istek örneğidir; anahtar ortam değişkeninden okunur ve komut satırında görüntülenmez. Yanıt geldikten sonra HTTP hatalarını ve JSON yapısını kontrol edin, ardından dönen her hizmeti ayrı ayrı işleyin. Şemadaki durum değerleri arasında operational, degraded, outage ve unknown bulunur; alan ya da değer yoksa kendiniz bir yorum eklemeyin.
İşlem gerektiren bir sinyal için ilgili hizmetin mevcut durumunu /v1/status üzerinden, geçmişini de /v1/history üzerinden sorgulayın. Geçmiş verisinde resolution_seconds, samples, counts ve effective_start değerlerini serilerle birlikte saklamak yararlıdır: böylece analist verilerin hangi zamansal çözünürlükle toplandığını ve hangi gerçek zaman aralığı için mevcut olduğunu görebilir. Spesifikasyon, eksik aralıkların bilinmediği konusunda uyarır; boş bir aralık otomatik olarak ne erişilebilirlik ne de kesinti kabul edilmelidir.
Yanıtı doğrulanabilir bir rapora dönüştürme
Her kayıt için şu alanları oluşturun: hizmetin kimliği ve adı, istek bölgesi, durum, gözlem zamanı, eski olma işareti, yanıtın alındığı zaman ve ekip tarafından kontrol edilmişse resmî durum kaynağına giden bağlantı. Son alanı entegrasyonunuz veya operatörünüz doldurur: UptimeScout spesifikasyonu, sinyalin doğrulanmış bir neden ya da sağlayıcı açıklaması içereceğini garanti etmez.

İş akışını üç duruma ayırın. “Sinyal alındı”, kaydın /v1/incidents sonucuna girdiği anlamına gelir. “Durum kontrol ediliyor”, mevcut durumu ve geçmişi sorguladığınız anlamına gelir. “Doğrulandı” ifadesini ise haricî bir resmî açıklamayla veya kurum içi bir kontrolle desteklenen sonuçlar için kullanın. Bu basit ayrım, gösterge panelinin toplulaştırılmış bir sinyali kesinleşmiş bir olgu gibi sunmasını önler.
Ekip birden fazla bölge için rapor hazırlıyorsa gereken bölge kodlarıyla ayrı istekler gönderin ve parametreyi sonuçla birlikte saklayın. lang alanı hizmet açıklamalarının dilini belirler; gözlem bölgesini değiştirmez. Örneğin yerelleştirilmiş bir katalogla bölgesel durumu karşılaştırırken bu ayrım önemlidir.
Çıkarımın sınırı
Bu senaryoda doğrulanabilir sonuç; zaman, bölge ve güncellik bilgileri açıkça belirtilmiş, durum ve geçmiş için ayrıca çapraz kontrol yapılmış bir sinyal günlüğüdür. Bu günlük, tam olarak neyin dikkat gerektirdiğini ve seçilen kaynaklar üzerinden nelerin doğrulanabildiğini ortaya koymaya yardımcı olur. /v1/incidents yanıtının kendisi, yükselmiş bir gözlem sinyali bildirir; doğrulanmış bir kesinti ilan etmek için bunu destekleyen veriler gerekir.