API v2

API v2 управляет Kraken по HTTP и возвращает ответы в JSON. Доступен при активном лицензионном ключевом файле. Команды v1 работают в Community Edition и описаны на странице API.

Актуально для Kraken 2.23.0.

Быстрый старт

  1. Включите API в Settings и задайте ключ в поле API Key.
  2. Скопируйте ключ.
  3. Проверьте доступ: GET /v2/settings с заголовком X-API-KEY.

Базовый URL и авторизация

Базовый URL: http://127.0.0.1:6015. Порт по умолчанию - 6015, меняется в Settings.

Авторизация - только заголовок X-API-KEY. Ключ задается в Settings; в query-строке ключ не принимается.

curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/settings

Формат запросов:

  • GET - параметры в query-строке, тело пустое;
  • POST - тело в формате JSON (Content-Type: application/json);
  • DELETE - тело пустое, объект указан в пути.

Все ответы, кроме ошибки авторизации и отказа без активного лицензионного ключевого файла, имеют Content-Type: application/json; charset=utf-8.

Коды ответов

  • 200 - запрос выполнен.
  • 201 - объект создан или запущен.
  • 400 - невалидный JSON или значение параметра.
  • 401 - неверный или отсутствующий API-ключ. Тело ответа пустое.
  • 404 - объект не найден или API v2 недоступен без активного лицензионного ключевого файла.
  • 405 - метод не поддерживается; в ответе заголовок Allow.
  • 409 - конфликт: объект уже существует или операция не завершилась.
  • 423 - конфликт состояния: отправка или мониторинг уже запущены либо еще не запущены.
  • 429 - превышен лимит запросов; в ответе заголовок Retry-After.
  • 500 - внутренняя ошибка.
  • 502 - API-ключ не задан в Settings; API не принимает запросы.

Ошибки возвращаются объектом с одним полем:

{"error":"not found"}

Коды 401, 404 (без PRO), 405, 429, 500 и 502 относятся ко всем методам. Ниже для каждого метода показан пример успешного ответа и, где это полезно, пример ошибки.

Без активного лицензионного ключевого файла любой запрос к /v2/ получает 404 с текстом API v2 requires a PRO license. Здесь тело - обычный текст, а не JSON.

Эндпоинты

Настройки

[PRO] GET /v2/settings

Возвращает текущие настройки отправки.

Параметров нет.

curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/settings

Пример ответа:

{
  "flow_distribution": 0,
  "flow_distribution_name": "Normal",
  "eps": 9000,
  "send_count": 1,
  "message_threads": 3
}
  • flow_distribution - распределение потока: 0 - Normal, 1 - Random, 2 - Duplicate.
  • flow_distribution_name - название режима.
  • eps - целевой EPS.
  • send_count - количество потоков отправки.
  • message_threads - количество потоков генерации.

[PRO] POST /v2/settings

Изменяет распределение потока и лимит EPS. Остальные поля не меняются. Возвращает настройки в том же виде, что и GET.

Тело запроса:

{
  "flow_distribution": 2,
  "eps": 5000
}

Поля необязательны; передавайте только те, которые нужно изменить.

curl -X POST -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"flow_distribution":2,"eps":5000}' \
  http://127.0.0.1:6015/v2/settings

Пример ответа:

{
  "flow_distribution": 2,
  "flow_distribution_name": "Duplicate",
  "eps": 5000,
  "send_count": 1,
  "message_threads": 3
}

Ошибки:

  • 400 - невалидное значение:
{"error":"flow_distribution must be an integer in 0..2"}
  • 400 - отрицательный EPS:
{"error":"eps must be a non-negative integer"}
  • 405 - метод не поддерживается:
{"error":"method not allowed"}

Маршруты

[PRO] GET /v2/routes

Возвращает список маршрутов.

curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/routes

Пример ответа:

[
  {
    "id": "1",
    "name": "Nginx",
    "host": "10.0.0.10",
    "port": "514",
    "proto": "UDP",
    "active": false
  }
]

[PRO] POST /v2/routes

Создает маршрут. Обязательные поля - name (имя шаблона), host, port. Поле proto необязательно, по умолчанию UDP.

Тело запроса:

{
  "name": "Nginx",
  "host": "10.0.0.10",
  "port": 514,
  "proto": "UDP"
}
curl -X POST -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Nginx","host":"10.0.0.10","port":514}' \
  http://127.0.0.1:6015/v2/routes

Пример ответа 201:

{"id":"2"}

Ошибки:

  • 400 - нет обязательного поля или невалидное значение:
{"error":"name is required"}
  • 400 - шаблон не найден:
{"error":"template not found: Custom"}
  • 400 - порт вне диапазона:
{"error":"port must be in the range 1..65535"}

[PRO] POST /v2/routes/{id}/start

Запускает отправку сообщений по всем маршрутам. Указанный маршрут должен существовать; проверка не меняет поведение кнопки Start в Messages.

curl -X POST -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/routes/1/start

Пример ответа:

{"status":"started"}

Ошибки:

  • 404 - маршрут не найден:
{"error":"route not found"}
  • 423 - отправка уже идет:
{"error":"messages are already running"}
  • 409 - запуск не удался; в тексте ошибки причина от проверки маршрутов.

[PRO] POST /v2/routes/{id}/stop

Останавливает отправку сообщений.

curl -X POST -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/routes/1/stop

Пример ответа:

{"status":"stopped"}

Ошибки:

  • 404 - маршрут не найден.
  • 423 - отправка не запущена:
{"error":"messages are not running"}

[PRO] DELETE /v2/routes/{id}

Удаляет маршрут. Эквивалентная команда - POST /v2/routes/{id}/delete.

curl -X DELETE -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/routes/2

Пример ответа:

{"status":"deleted"}

Ошибки:

  • 404 - маршрут не найден.
  • 500 - маршрут не удален:
{"error":"route could not be deleted"}

Отправка и статистика

[PRO] POST /v2/messages/start

Запускает отправку сообщений по всем маршрутам.

curl -X POST -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/messages/start

Пример ответа:

{"status":"started"}

Ошибки:

  • 423 - отправка уже идет:
{"error":"messages are already running"}
  • 400 - ошибка проверки маршрута или шаблона; текст ошибки содержит причину.
  • 409 - запуск не удался по другой причине.

[PRO] POST /v2/messages/stop

Останавливает отправку сообщений.

curl -X POST -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/messages/stop

Пример ответа:

{"status":"stopped"}

Ошибка 423:

{"error":"messages are not running"}

[PRO] GET /v2/statistics

Возвращает текущую статистику отправки.

curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/statistics

Пример ответа:

{
  "Messages": true,
  "EPS": 15000,
  "AVG": 14850,
  "Sending": 1234567,
  "Time": 42
}
  • Messages - признак активной отправки.
  • EPS - текущий EPS.
  • AVG - средний EPS.
  • Sending - количество отправленных событий.
  • Time - время работы, секунд.

Шаблоны, плейбуки и профили

[PRO] GET /v2/templates

Возвращает список шаблонов из каталога etc.

curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/templates

Пример ответа:

[
  {
    "name": "Nginx",
    "author": "",
    "version": 3,
    "enable": true,
    "index": "Test",
    "type": "_doc"
  }
]

[PRO] POST /v2/templates

Создает шаблон. Обязательное поле - name. Остальные поля необязательны: author, index, type, enable, overwrite, json, post, templates, message.

Тело запроса:

{
  "name": "Custom",
  "index": "Test",
  "type": "_doc",
  "templates": ["custom event from {hostname}"]
}
curl -X POST -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Custom","templates":["custom event"]}' \
  http://127.0.0.1:6015/v2/templates

Пример ответа 201:

{"name":"Custom","status":"created"}

Ошибки:

  • 400 - невалидное имя:
{"error":"name is invalid"}
  • 409 - шаблон уже существует:
{"error":"template already exists: Custom"}

[PRO] DELETE /v2/templates/{name}

Удаляет шаблон по имени.

curl -X DELETE -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/templates/Custom

Пример ответа:

{"status":"deleted"}

Ошибки:

  • 404 - шаблон не найден:
{"error":"template not found: Custom"}
  • 500 - шаблон не удален.

[PRO] GET /v2/playbooks

Возвращает список плейбуков.

curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/playbooks

Пример ответа:

[
  {
    "id": "3f2a6c1e-9b7d-4c2a-8e5f-1a2b3c4d5e6f",
    "name": "Base scenario"
  }
]

[PRO] POST /v2/playbooks/{id}/run

Запускает плейбук по идентификатору.

curl -X POST -H "X-API-KEY: $API_KEY" \
  http://127.0.0.1:6015/v2/playbooks/3f2a6c1e-9b7d-4c2a-8e5f-1a2b3c4d5e6f/run

Пример ответа 201:

{"status":"started"}

Ошибка 404:

{"error":"playbook not found"}

[PRO] GET /v2/profiles

Возвращает список профилей Messages.

curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/profiles

Пример ответа:

[
  {
    "name": "Default"
  }
]

[PRO] POST /v2/profiles/{name}/select

Выбирает профиль Messages. Эквивалентная команда - POST /v2/profiles/{name}/apply.

curl -X POST -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/profiles/Default/select

Пример ответа:

{"status":"selected"}

Ошибки:

  • 404 - профиль не найден:
{"error":"profile not found: Default"}
  • 423 - отправка запущена, профиль менять нельзя:
{"error":"messages are running"}

Мониторинг

[PRO] GET /v2/monitoring

Возвращает состояние мониторинга.

curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/monitoring

Пример ответа:

{
  "running": false,
  "uptime": 0,
  "samples": 0,
  "host": "192.0.2.10",
  "port": 22
}
  • running - мониторинг запущен.
  • uptime - время работы, секунд.
  • samples - количество собранных измерений.
  • host, port - узел мониторинга из Settings.

[PRO] POST /v2/monitoring/start

Запускает мониторинг и отвечает после смены состояния.

curl -X POST -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/monitoring/start

Пример ответа:

{"status":"started"}

Ошибки:

  • 423 - мониторинг уже запущен:
{"error":"monitoring is already running"}
  • 423 - предыдущий запуск или остановка еще выполняются:
{"error":"monitoring transition in progress"}
  • 409 - состояние не изменилось:
{"error":"monitoring did not start"}
  • 500 - ошибка запуска; текст содержит причину.

[PRO] POST /v2/monitoring/stop

Останавливает мониторинг и отвечает после смены состояния.

curl -X POST -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/monitoring/stop

Пример ответа:

{"status":"stopped"}

Ошибки:

  • 423 - мониторинг не запущен:
{"error":"monitoring is not running"}
  • 423 - переход уже выполняется:
{"error":"monitoring transition in progress"}
  • 409 - состояние не изменилось:
{"error":"monitoring did not stop"}
  • 500 - ошибка остановки; текст содержит причину.

Ограничения

  • API не использует TLS: порт 6015 должен быть доступен только из доверенной сети.
  • Лимит запросов - 600 за 60 секунд с одного IP; при превышении 429 и заголовок Retry-After.
  • Для работы API v2 нужен активный лицензионный ключевой файл.

Связанные разделы

Поделиться с друзьями