Чи можна за відповіддю UptimeScout incidents одразу оголосити, що в сервісі аварія? Ні: цей ендпойнт перелічує сервіси з нещодавніми підвищеними сигналами порушень, а специфікація прямо зазначає, що це не підтверджені інциденти провайдера. Практичний результат — короткий список сигналів для перевірки, а не готовий висновок про причину збою.

Це корисне розрізнення для чергового інженера й аналітика: автоматичне сповіщення може сказати «перевірте сервіс X у регіоні Y», залишаючи підтвердження факту та пояснення причини за офіційним статусом провайдера або власною діагностикою. Специфікація UptimeScout описує окремі маршрути для сигналів, поточного статусу й історії спостережень.
Що саме повертає список сигналів
/v1/incidents — GET-ендпойнт каталогу сервісів із підвищеними сигналами порушень. Серед його параметрів є фільтри за сервісом, регіоном, категорією, пошуковим запитом і часовим вікном. Для відповіді потрібна ліцензія; API описує авторизацію за допомогою Bearer-токена. Поле регіону приймає дволітерний код, а hours задає вікно від 1 до 2160 годин.
Слово «incident» у шляху легко прочитати як «підтверджена аварія», але документація надає йому вужчого значення: свіжий сигнал спостережень. Тож сповіщення варто формулювати відповідно до даних відповіді — наприклад, «отримано сигнал про порушення доступності» — і не приписувати постачальнику послуги визнання інциденту.
Мінімальна перевірка перед сповіщенням
Спочатку збережіть початкову відповідь разом із часом отримання та параметрами запиту. Потім перевірте, який сервіс і регіон повернулися, та оцініть актуальність за полями сервісу observed_at і stale. Якщо спостереження позначено як застаріле, його слід відокремити від поточного сигналу, а не показувати як стан «прямо зараз».
curl -sS 'https://api.uptimescout.com/v1/incidents?region=US&hours=24' \
-H "Authorization: Bearer $UPTIMESCOUT_LICENSE_KEY"
Це приклад запиту для США за 24-годинне вікно; ключ зчитується зі змінної середовища й не відображається в командному рядку. Після відповіді перевірте HTTP-помилки та структуру JSON, а потім обробіть кожен повернений сервіс окремо. Значення статусу в схемі включають operational, degraded, outage і unknown; якщо поля або значення немає, не підставляйте власну інтерпретацію.
Для сигналу, що потребує дії, запитайте поточний статус відповідного сервісу через /v1/status та історію через /v1/history. В історії корисно зберігати поруч із часовими рядами resolution_seconds, samples, counts і effective_start: так аналітик бачить, із якою часовою деталізацією зібрано дані та за який фактичний інтервал вони доступні. Специфікація попереджає, що пропущені інтервали невідомі; порожній проміжок не можна автоматично вважати ані доступністю, ані збоєм.
Як перетворити відповідь на звіт, який можна перевірити
Для кожного запису створіть поля: ідентифікатор і назва сервісу, регіон запиту, статус, час спостереження, ознака застарілості, час отримання відповіді та посилання на джерело офіційного статусу, якщо команда його перевірила. Останнє поле заповнює ваша інтеграція або оператор: специфікація UptimeScout не гарантує, що сигнал містить підтверджену причину чи заяву провайдера.

Розділіть робочий процес на три стани. «Сигнал отримано» означає, що запис потрапив до результату /v1/incidents. «Статус звіряється» означає, що ви запросили поточний стан та історію. «Підтверджено» залишайте для висновку, підкріпленого зовнішнім офіційним повідомленням або внутрішньою перевіркою. Таке просте розділення не дає інформаційній панелі видавати агрегований сигнал за встановлений факт.
Якщо команда готує звіт за кількома регіонами, виконуйте окремі запити з потрібними кодами регіонів і зберігайте параметр разом із результатом. Поле lang стосується мови описів сервісів; воно не змінює регіон спостережень. Це розрізнення важливе під час порівняння, наприклад, локалізованого каталогу й регіонального стану.
Де закінчуються висновки
Результат цього сценарію, який можна перевірити, — журнал сигналів із чіткими позначками часу, регіону й актуальності, доповнений окремою звіркою статусу та історії. Він допомагає виявити, що саме потребує уваги та що вдалося підтвердити за вибраними джерелами. Сама відповідь /v1/incidents повідомляє про підвищений сигнал спостережень; щоб оголосити підтверджену аварію, потрібні підтверджувальні дані.