Відповідних розділів не знайдено.

Host-Tracker REST API v1

Стабільний HTTP API з токен-автентифікацією для керування задачами моніторингу вебсайтів, контактами, підписками на сповіщення/звіти та читання статистики, простоїв та інцидентів.

Базова URL-адреса

Кожен шлях у цьому документі є відносним до базової URL-адреси. Дві точки входу обслуговують один і той самий API:

У цьому довіднику виклик, записаний як GET tasks, означає GET BASE_URL/tasks — тобто https://api1.host-tracker.com/tasks або https://www.host-tracker.com/api/web/v1/tasks.

Тип вмісту та методи HTTP

За замовчуванням запити та відповіді мають тип application/json (див. Угоди щодо XML). API використовує стандартні методи HTTP:

• GET — читання сутностей (задачі, контакти, підписки, статистика, простої, інциденти, агенти).
• POST — створення сутності або запуск дії.
• PUT — оновлення наявних сутностей.
• DELETE — видалення сутностей.
• PATCH — часткові оновлення (використовується для повторного надсилання коду підтвердження контакту).

Перевизначення HTTP-методу

Якщо ваш клієнт не може надсилати PUT, DELETE чи PATCH, надішліть POST і додайте заголовок X-HTTP-Method-Override із назвою потрібного методу. Наприклад, щоб оновити задачі, надішліть POST на tasks із X-HTTP-Method-Override: PUT.

Угоди

Серіалізація JSON

JSON використовує назви властивостей у стилі camelCase. Порожні (null) поля пропускаються у відповідях (порожні масиви все одно передаються як []). Порядок властивостей стабільний: спочатку ідентифікатор та адреса/url, потім успадковані поля, потім поля, специфічні для типу.

Дата та час

Відповіді на створення/читання задач містять мітки часу у вигляді рядків ISO-8601 UTC (наприклад, 2024-06-21T22:26:23Z). Кінцеві точки статистики, простоїв, інцидентів та результатів додатково використовують подвійне представлення: кожен час подається і як ціле число в секундах Unix (суфікс Unix), і як зручний для читання рядок, відформатований відповідно до формату дати та часового поясу профілю облікового запису. Фільтри запитів приймають секунди Unix та/або відформатовані рядки залежно від кінцевої точки (це задокументовано для кожної кінцевої точки нижче). Усі мітки часу Unix — це секунди від 1970-01-01T00:00:00Z.

Узгодження вмісту XML

Усі кінцеві точки також можуть повертати XML. Надішліть Accept: application/xml, щоб отримати тіло у форматі XML замість JSON; відповідь використовує класичне представлення .NET XmlSerializer того самого графа об'єктів. JSON — формат за замовчуванням і рекомендований.

CORS

Крос-доменні запити дозволені. Прості (без облікових даних) запити приймаються з будь-якого джерела (Access-Control-Allow-Origin: *). Запити, що надсилають cookie/облікові дані, приймаються лише з джерел *.host-tracker.com. Клієнти, що використовують токен (через заголовок Authorization, як описано тут), не підпадають під це обмеження джерел з обліковими даними.

Автентифікація

Кожна кінцева точка, окрім POST users/token та анонімних кінцевих точок списку агентів, вимагає автентифікації. Приймаються дві схеми:

• Bearer-токен — отримується з POST users/token, надсилається як Authorization: bearer <token>. Це основна схема.
• HTTP Basic — Authorization: Basic <base64(login:password)>. Облікові дані декодуються як ISO-8859-1. Зручно для швидких тестів; для автоматизації перевага надається bearer-токену.

POST users/token анонімно

Обмін логіна та пароля на bearer-токен. Токен дійсний протягом 48 годин.

Тіло запиту

{
  "login": "your-login",
  "password": "your-password"
}

Відповідь — 200 OK

{
  "ticket": "<bearer token>",
  "expirationTime": "2024-06-23T22:26:23Z",
  "expirationUnixTime": 1719181583
}

У разі невдачі відповідь — 401 із машинним кодом IncorrectLoginOrPassword (або AccessDenied, якщо доступ до API вимкнено для облікового запису) та заголовком WWW-Authenticate: Bearer.

Використання токена

GET BASE_URL/tasks HTTP/1.1
Host: api1.host-tracker.com
Accept: application/json
Authorization: bearer 3DD135...5EE510417

Імперсонація субоблікового запису (forLogin)

Якщо супер-обліковий запис надав вашому субобліковому запису доступ до своїх даних, увійдіть як субобліковий запис, але передайте логін супер-облікового запису у forLogin. Отриманий токен тоді дозволяє керувати супер-обліковим записом так, ніби кінцеві точки викликаються для вашого власного облікового запису, з урахуванням прав, наданих супер-обліковим записом. Наприклад, якщо надано доступ лише для читання до задач моніторингу, GET-запити виконуються успішно, але POST/PUT/PATCH/DELETE щодо задач відхиляються.

# 1. Отримати токен імперсонації
POST BASE_URL/users/token HTTP/1.1
Content-Type: application/json

{
  "login": "subaccount-login",
  "password": "subaccount-password",
  "forLogin": "superaccount-login"
}

# 2. Використати отриманий ticket, щоб прочитати задачі СУПЕР-облікового запису
GET BASE_URL/tasks HTTP/1.1
Authorization: bearer <ticket from step 1>

curl

# отримати токен і зберегти його
TOKEN=$(curl -s -X POST https://api1.host-tracker.com/users/token \
  -H "Content-Type: application/json" \
  -d '{"login":"your-login","password":"your-password"}' \
  | grep -o '"ticket":"[^"]*"' | cut -d'"' -f4)

# виклик автентифікованої кінцевої точки
curl -s https://api1.host-tracker.com/tasks \
  -H "Authorization: bearer $TOKEN"

Помилки та машинні коди

Помилки повертають стандартний HTTP-код статусу плюс короткий машинно-читаний код, за яким ваша інтеграція може розгалужувати логіку. Тіло відповіді — звичайний текстовий опис англійською (не JSON), призначений для людей/логів.

Машинний код передається двома способами:

• Заголовок відповіді X-HT-Reason — містить код у кожній відповіді та для будь-якої версії HTTP. Це рекомендований спосіб визначення типу помилки.
• Фраза причини HTTP/1.1 — рядок статусу виглядає, наприклад, як HTTP/1.1 400 SimilarExists. Збережено для зворотної сумісності, але зауважте, що HTTP/2 та HTTP/3 прибрали фрази причини з протоколу, тож це поле може бути порожнім, коли з'єднання узгоджує HTTP/2+. Надавайте перевагу X-HT-Reason.

HTTP/1.1 400 SimilarExists
X-HT-Reason: SimilarExists
Content-Type: text/plain; charset=utf-8

Same task allready exists

Довідник кодів помилок

Кожен машинний код, який може повернути API, згрупований за областю, з типовим HTTP-статусом. Якщо не зазначено інше, помилки мають статус 400 Bad Request.

Автентифікація

Задачі

Контакти

Підписки

Обмеження частоти запитів

Запити обмежуються за частотою для кожного клієнта окремо на кожній кінцевій точці. Перевищення ліміту повертає 429 з машинним кодом RequestThrottled та заголовком Retry-After (у секундах).

HTTP/1.1 429 RequestThrottled
X-HT-Reason: RequestThrottled
Retry-After: 1
Content-Type: application/json; charset=utf-8

"API calls quota exceeded! maximum admitted 6 per s."

Задачі моніторингу

GET tasks/types

Повертає масив назв типів задач, відомих системі:

["API","CntCheck","Counter","DNSBL","Database","DomainExp","Http",
 "Ping","Port","RusRegBL","SSLExp","Snmp","Tran","Waterfall","WebRisk"]

GET tasks/intervals

Повертає масив інтервалів моніторингу (у хвилинах), прийнятних для вашого облікового запису, наприклад [1,5,15,30,60]. Використовуйте одне з цих значень для поля interval під час створення задачі; будь-яке інше значення призводить до WrongInterval.

GET tasks

Список задач моніторингу. Усі параметри запиту необов'язкові; без жодного повертаються всі задачі облікового запису. Повторіть параметр, щоб передати масив, наприклад ?ids=guid1&ids=guid2.

Параметр info

Запитує додаткові дані, вбудовані в кожну задачу. Поєднуйте значення комами (?info=stats,subscriptions) або передайте еквівалентне ціле число бітової маски:

?info=stats,subscriptions,results еквівалентний ?info=7.

Параметри фільтра

Відповідь — 200 OK

Масив об'єктів задач. Точний набір полів залежить від типу задачі; спільна база включає id, name, taskType, enabled, interval, lastState, creationTime, tags, agentPools, а також (якщо запитано через info) subscriptions, stats, results і attached. Коли включено результати, кожен результат містить принаймні timestamp (секунди Unix, UTC) та eventNumber; решта полів специфічні для типу задачі (див. відповідь створення нижче для форми HTTP).

GET BASE_URL/tasks?info=stats,subscriptions&taskType=Http HTTP/1.1
Accept: application/json
Authorization: bearer <token>

GET tasks/{id:guid}

Отримати одну задачу за id. Приймає той самий параметр info (та sdtu/edtu, коли info=results). Повертає об'єкт задачі або 404 NotFound, якщо вона не існує.

POST tasks/http · tasks/ping · tasks/port · tasks/rusbl

Створити задачу моніторингу заданого типу. У разі успіху повертається 201 Created, відносний заголовок Location: /tasks/{id} та повний об'єкт створеної задачі.

Тіло запиту — задача HTTP

{
  // поля, специфічні для HTTP
  "url": "https://www.example.com",        // ОБОВ'ЯЗКОВЕ
  "httpMethod": "Get",                       // Get | Post | Head (за замовчуванням Get)
  "userAgent": "MyMonitor",
  "referer": "https://www.google.com",
  "acceptHeader": "application/json",
  "followRedirect": false,
  "treat300AsError": false,                // якщо встановлено, followRedirect ігнорується
  "checkDnsbl": false,                       // перевіряти домен на DNS-чорні списки
  "checkDomainExpiration": false,            // моніторити закінчення терміну дії домену (лише для валідних доменів)
  "checkCertificateExpiration": false,       // моніторити закінчення терміну дії TLS-сертифіката (лише https)
  "checkRussianBlackLists": false,
  "checkWebRisk": false,
  "timeout": 40000,                          // мс до провалу перевірки
  "keywords": ["error", "maintenance"],
  "keywordMode": "ReverseAny",             // див. режими ключових слів нижче
  "userName": "basic-auth-user",          // облікові дані для моніторованого ресурсу
  "password": "basic-auth-pass",
  "postParameters": "a=1\r\nb=2",          // лише з httpMethod=Post
  "ignoredStatuses": [404, 500],

  // поля, спільні для кожного типу задачі
  "interval": 5,                             // хвилини; має бути прийнятним інтервалом
  "enabled": true,
  "fullLog": false,                          // лише розширені пакети
  "openStat": true,
  "name": "My website",
  "tags": ["production", "web"],
  "agentPools": ["westeurope", "asia"],  // див. примітки нижче
  "subscriptions": [ /* вбудовані підписки, див. нижче */ ]
}

Вбудовані підписки

Масив subscriptions підписує контакти на сповіщення/звіти цієї задачі під час створення. Кожен запис використовує форму підписки; не встановлюйте taskIds (він фіксований на нову задачу). Якщо contactIds опущено, підписуються всі ваші підтверджені контакти. Підписки на звіти застосовуються лише до контактів типу Email.

Інші типи задач

• tasks/ping — тіло містить host плюс спільні поля.
• tasks/port — тіло містить host та port плюс спільні поля.
• tasks/rusbl — перевірка чорного списку російського реєстру; тіло містить url, а також ignoreWarnings, doNotSendMsgOnWarnings, prefixMatch та спільні поля.

Відповідь — 201 Created (задача HTTP)

{
  "id": "ef10cd12-93f9-e311-bec5-dc85de1f0bc2",
  "url": "https://www.example.com",
  "rawUrl": "https://www.example.com",
  "name": "My website",
  "creationTime": "2024-06-21T22:26:23Z",
  "taskType": "Http",
  "enabled": true,
  "interval": 5,
  "lastState": true,
  "openStatEnabled": true,
  "fullLogEnabled": false,
  "tags": ["production", "web"],
  "agentPools": ["westeurope", "asia"],
  "subscriptions": [
    { "alertTypes": ["Up"],   "taskIds": ["ef10cd12-...-0bc2"], "contactIds": ["4cedf037-...-0bc2"] },
    { "alertTypes": ["Down"], "taskIds": ["ef10cd12-...-0bc2"], "contactIds": ["4cedf037-...-0bc2"] },
    { "reportTypes": ["Month"], "taskIds": ["ef10cd12-...-0bc2"], "contactIds": ["4cedf037-...-0bc2"] }
  ],
  "httpMethod": "Get",
  "keywords": ["error"],
  "keywordMode": "ReverseAny",
  "timeout": 40000
}

curl

curl -s -X POST https://api1.host-tracker.com/tasks/http \
  -H "Authorization: bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.example.com","interval":5,"name":"My website"}'

PUT tasks & типізовані варіанти

Оновлення задач. Дві форми:

• За id — PUT tasks/{id} (лише спільні поля), або типізовані PUT tasks/http/{id}, tasks/ping/{id}, tasks/port/{id}, tasks/rusbl/{id} (також поля, специфічні для типу). Тіло має ту саму редаговану форму, що й при створенні; змінюються лише надіслані вами поля.
• За фільтром — PUT tasks?<filter> (лише спільні поля) або типізований PUT tasks/{type}?<filter> (прив'язує фільтр до цього типу). Використовує ті самі параметри фільтра, що й GET tasks. Повертає оновлену задачу(і).

Нетипізований PUT tasks / PUT tasks/{id} може торкатися лише полів, спільних для всіх типів задач — для зміни налаштувань, специфічних для типу, використовуйте типізовану кінцеву точку.

DELETE tasks/{id:guid} & tasks

• DELETE tasks/{id} — видалити одну задачу; повертає видалену задачу.
• DELETE tasks?<filter> — масове видалення за фільтром задач (фільтр також можна передати в тілі запиту). Повертає видалені задачі.

POST tasks/$batch · task/$batch

Виконати кілька операцій із задачами в одному запиті. Тіло — масив JSON з підзапитами; відповідь — масив JSON з підвідповідями в тому самому порядку. Підоперація обирається за останнім сегментом relativeUrl (наприклад, http → POST tasks/http). Тіло запиту має бути JSON (Content-Type: application/json). Такий самий механізм існує для контактів на contacts/$batch / contact/$batch.

POST BASE_URL/tasks/$batch HTTP/1.1
Authorization: bearer <token>
Content-Type: application/json

[
  {
    "method": "POST",
    "relativeUrl": "http",
    "contentType": "application/json",
    "content": "{\"url\":\"https://a.example.com\",\"interval\":5}"
  },
  {
    "method": "POST",
    "relativeUrl": "ping",
    "contentType": "application/json",
    "content": "{\"host\":\"b.example.com\"}"
  }
]

[
  { "code": 201, "status": "Created",
    "headers": { "Location": "/tasks/ef10cd12-...-0bc2" },
    "body": "{ ...created http task... }" },
  { "code": 201, "status": "Created",
    "headers": { "Location": "/tasks/7a20de34-...-1cd3" },
    "body": "{ ...created ping task... }" }
]

Контакти

Контакти — це адресати, які отримують сповіщення та звіти (email-адреси, номери телефонів для SMS/дзвінків). Id контактів використовуються під час створення підписок.

GET contacts/types · contacts/delays · contacts/sms/gateways · contacts/im/gateways

Статичні перелічення, які використовуються кінцевими точками контактів:

GET contacts & contacts/{id:guid}

Список контактів (з опційним фільтром) або отримання одного за id. Додайте ?info=subscriptions, щоб вбудувати підписки кожного контакту. Без фільтра повертаються всі контакти облікового запису.

Об'єкт контакту

Спільні поля: id, confirmed, contactType, name, address, alertDelay, activePeriodStart/activePeriodEnd (HH:mm), activeDays, sendCost. Email-контакти додатково мають reportFormat (Text/ShortText), sendNews, sendBillingNotifications; SMS/IM-контакти додатково мають gateway.

POST contacts/email · contacts/sms · contacts/voice

Створити контакт. Повертає 201 Created, відносний Location: /contacts/{id} та ContactOperationResult ({ contact, status }), чий status повідомляє результат підтвердження.

{
  "address": "ops@@example.com",          // ОБОВ'ЯЗКОВЕ
  "name": "Ops mailbox",
  "alertDelay": 0,                        // хвилини; одне зі значень contacts/delays
  "reportFormat": "Text",               // Text | ShortText (лише email)
  "activePeriodStart": "00:00",        // необов'язкове вікно тихих годин (HH:mm)
  "activePeriodEnd": "23:59",
  "activeDays": ["Monday", "Tuesday"],   // необов'язкове; за замовчуванням усі дні
  "subscriptions": [ /* необов'язкові вбудовані підписки */ ]
}

SMS- та voice-контакти за замовчуванням використовують шлюзи twiliosms / twiliovoice, отримують типову ціну за повідомлення та зберігають номер із провідним +. Зміна адреси чи шлюзу контакту скидає його стан підтвердження.

Значення статусу підтвердження

Поле status результату повідомляє результат надсилання коду підтвердження:

PUT contacts & типізовані варіанти

• За id — PUT contacts/{id} (спільні поля), або типізовані PUT contacts/email/{id}, contacts/sms/{id}, contacts/voice/{id}. Змінюються лише надіслані вами поля.
• За фільтром — PUT contacts?<filter> або типізований PUT contacts/{type}?<filter> (прив'язує фільтр до цього типу), за допомогою фільтра контактів.

PUT contacts/im (обидві форми) повертає 400 WrongContactType.

DELETE contacts/{id:guid} & contacts

Видалити один контакт за id, або масово видалити за фільтром контактів. Як і для задач, масове видалення з порожнім фільтром відхиляється з 400 EmptyFilter.

Коди підтвердження

Непідтверджені контакти мають підтвердити володіння коротким кодом, доставленим на адресу контакту.

• PATCH contacts/{id}/code — (повторно) видати та надіслати код підтвердження. Повертає ContactOperationResult зі статусом, як-от CodeSent.
• POST contacts/{id}/code — підтвердити контакт, надіславши код. Тіло: { "code": "12345" }. У разі успіху контакт стає підтвердженим.

Сповіщення та підписки

Підписка пов'язує одну або кілька задач і контактів із набором типів сповіщень та/або звітів. Один запис підписки утворює декартів добуток своїх задач і контактів, породжуючи одне сповіщення/звіт на кожну пару (задача, контакт, тип).

Форма підписки

{
  "alertTypes": ["Up", "Down"],       // будь-які з Up, Down, RepeatedlyDown
  "reportTypes": ["Day", "Month"],     // будь-які з Day, Week, Month, Quarter, Year
  "taskIds": ["<task guid>"],
  "contactIds": ["<contact guid>"]
}

• Потрібне принаймні одне з alertTypes / reportTypes, інакше — AlertsAndReportsAreEmpty.
• Пропуск taskIds за замовчуванням означає усі ваші задачі; пропуск contactIds за замовчуванням означає усі ваші контакти. Явний порожній масив означає "жодного".
• Підписки на звіти застосовуються лише до Email-контактів — типи звітів на не-Email контактах мовчки ігноруються (їхні підписки на сповіщення все одно створюються).
• Id, якими ви не володієте, ігноруються.

GET subscriptions/alertTypes · subscriptions/reportTypes

GET subscriptions

Список підписок. Повертає один запис на кожну зіставлену підписку на сповіщення чи звіт (ніколи не об'єднуються). Необов'язкові фільтри:

POST subscriptions · DELETE subscriptions

Обидва приймають масив JSON із записами підписок у тілі. POST додає описані підписки (вставляються лише нові рядки); DELETE видаляє наявні. Обидва повертають 200 OK з порожнім тілом. Невідомі типи сповіщень/звітів відхиляються з UnknownAlertType / UnknownReportType.

[
  { "alertTypes": ["Up", "Down"],
    "taskIds": ["7ee87894-b8a9-e311-beb2-dc85de1f0bc2"],
    "contactIds": ["4cedf037-d1d9-e311-bebc-dc85de1f0bc2"] },
  { "reportTypes": ["Month"],
    "taskIds": ["7ee87894-b8a9-e311-beb2-dc85de1f0bc2"],
    "contactIds": ["4cedf037-d1d9-e311-bebc-dc85de1f0bc2"] }
]

curl -s -X POST https://api1.host-tracker.com/subscriptions \
  -H "Authorization: bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"alertTypes":["Up","Down"],"taskIds":["<task>"],"contactIds":["<contact>"]}]'

Статистика та результати

GET stats

Агрегати доступності/недоступності на задачу за часове вікно. Приймає фільтр задач для вибору задач, а також:

Відповідь

Об'єкт Stats з узгодженим вікном (подвійні поля дати) та масивом stats. Кожен запис містить посилання на задачу та: uptimeInMinutes/uptimeSpan, downtimeInMinutes/downtimeSpan, час обслуговування (uptime/downtime), totalTimeInMinutes, кількість перевірок за бакетами, та uptimePercent/downtimePercent.

GET outages

Проміжки недоступності на задачу. Приймає фільтр задач плюс:

Відповідь: об'єкт Outages з узгодженим вікном та масивом taskOutages; кожен елемент поєднує задачу з її проміжками outages (startTime/endTime + варіанти Unix, номери подій, необов'язковий коментар).

GET incident

Список інцидентів (подій збою) на задачу. Приймає фільтр задач плюс ті самі параметри вікна/часового поясу, що й для простоїв, а також:

Відповідь: об'єкт Incidents з масивом taskIncidents. Кожен інцидент містить taskId, checkId, час початку/кінця в Unix, місце збою location, error, hasSnapshot, і (з fullLog) блок recheck зі списком успішних локацій та проблемних локацій за кожною помилкою.

GET incident/snapshot

Отримати збережений знімок відповіді, захоплений для інциденту. Параметри:

Повертає знімок (мітку часу разом із захопленими байтами), якщо такий існує, або null, якщо для заданого інциденту знімка немає.

GET results/http

Агреговані метрики часу відповіді HTTP на задачу. Примусово встановлює тип задачі Http. Приймає фільтр задач плюс:

Відповідь: об'єкт AggregatedHttpResults; кожен запис taskResults повідомляє посилання на задачу та усереднені responseTime, dnsTime, headTime, dataTime (у мілісекундах).

GET cr/httpResponseTime

Ряди часу відповіді HTTP на задачу. Приймає фільтр задач плюс startDate, endDate та groupBy. Повертає простий масив об'єктів рядів:

[
  {
    "id": "ef10cd12-93f9-e311-bec5-dc85de1f0bc2",
    "rawUrl": "https://www.example.com",
    "name": "My website",
    "results": [ [1719181583, 142], [1719177983, 138] ]   // [секунди Unix, час відповіді у мс], спочатку найновіші
  }
]

Агенти

Агенти — це географічно розподілені місця моніторингу. Id пулів, що повертаються тут, — це значення, які ви передаєте в поле agentPools задачі.

GET agents

Список агентів моніторингу. Необов'язковий параметр запиту:

Кожен агент містить id, upFrom, datacenter (назва/місто/країна/область), company (назва/url), ip, version, lon/lat, та pools.

[
  {
    "id": "a1b2c3d4-...-0001",
    "upFrom": "2024-06-20T08:00:00Z",
    "datacenter": { "name": "Example Hosting", "city": "Frankfurt", "country": "DE", "state": "" },
    "company": { "name": "Example Hosting", "url": "https://example-hosting.com" },
    "ip": "203.0.113.10",
    "version": "1.4.2",
    "lon": 8.68, "lat": 50.11,
    "pools": []
  }
]

GET agents/pools

Список публічних пулів агентів (геозон). Кожен пул містить id, desc, свої agents, childPools та hidden. Використовуйте значення id пулу в полі agentPools задачі.

GET agents/ips анонімно

Повертає поточні IP-адреси агентів моніторингу — корисно для внесення Host-Tracker до білого списку міжмережевого екрана. Ця кінцева точка не потребує автентифікації. За замовчуванням вона повертає text/plain, по одній IP-адресі на рядок; надішліть Accept: application/json, щоб отримати замість цього масив JSON.

203.0.113.10
203.0.113.11
198.51.100.7

["203.0.113.10", "203.0.113.11", "198.51.100.7"]