API

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

API Kraken Stress Testing Toolkit предназначено для удалённого управления генератором событий и получения статистики. API работает по HTTP и использует GET-запросы; параметры передаются в query-строке.

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

  1. Включите API в разделе Settings → API и при необходимости измените порт (по умолчанию 6015). После смены порта перезапустите API или приложение.
  2. Скопируйте значение поля API KEY - оно уникально для каждой установки.
  3. Проверьте доступность API запросом к /state/live.

Код 200 означает, что API доступен. Если вернулся 401, проверьте ключ; если 502 - ключ не задан на сервере.

Базовый URL

Базовый адрес API: http://<host>:<port>, по умолчанию http://127.0.0.1:6015. API слушает HTTP без TLS - если нужен защищённый канал, используйте SSH-туннель, VPN или обратный прокси с TLS.

Смена порта выполняется в Settings → API. После изменения порта API нужно перезапустить.

Аутентификация

Для авторизации используется HTTP-заголовок X-API-KEY. Передача ключа в query-строке (?X-API-KEY=..., ?key=..., ?api_key=...) не поддерживается - такой запрос вернёт 401.

Ключ генерируется автоматически при первом запуске, уникален для каждой установки и хранится в config.db в зашифрованном виде (DPAPI). Ключ отображается в Settings → API; кнопка Re-create создаёт новый ключ. Старые статические ключи из предыдущих версий недействительны.

Формат запросов и ответов

  • Большинство команд выполняется методом GET; параметры передаются в query-строке и должны быть URL-кодированы.
  • Исключение - POST /templates/add: параметры передаются в теле application/x-www-form-urlencoded; GET с теми же параметрами сохранён для обратной совместимости.
  • Для остальных команд тело запроса не используется.
  • Длина GET-запроса ограничена request-line (около 16 КиБ); большие шаблоны добавляйте через POST.
  • Для большинства команд тело ответа пустое, а результат определяется HTTP-кодом.
  • Команды чтения возвращают простой текст: число, строку или список (по одному значению в строке).
  • JSON возвращает только /v2/statistics - см. раздел API v2.

Коды ответов

  • 200 - запрос успешно выполнен.
  • 201 - задача запущена (/play/..., /templates/add).
  • 400 - ошибка в параметрах запроса.
  • 401 - неверный или отсутствующий API-ключ.
  • 403 - недопустимое имя или путь (Path Traversal).
  • 404 - плейбук или элемент не найден.
  • 405 - метод не поддерживается для этого маршрута; допустимы GET и POST. Для /templates/add используйте POST.
  • 413 - слишком большое тело запроса или шаблона: тело POST больше 1 МиБ или message больше 256 КиБ.
  • 423 - операция недоступна в текущем состоянии: отправка уже запущена или ещё не запущена, либо профиль/правило нельзя изменить во время отправки.
  • 429 - превышен лимит запросов; см. заголовок Retry-After.
  • 500 - внутренняя ошибка сервера.
  • 502 - API-ключ не настроен на сервере.

Ограничения

  • 600 запросов в минуту с одного IP-адреса.
  • 20 неудачных попыток авторизации за 5 минут - блокировка IP на 15 минут.
  • Метод /templates/add - 10 запросов в минуту; тело POST-запроса - до 1 МиБ, длина GET-запроса - до ~16 КиБ.
  • Тело шаблона (параметр message) - не более 262 144 байт UTF-8 (256 КиБ).
  • Имя шаблона - не более 64 символов; имя профиля - не более 128 символов.

При превышении лимита возвращается 429 и заголовок Retry-After с количеством секунд до снятия блокировки.

Журналирование

Каждый запрос пишется в access-лог logs\access_ГГГГММДД.log в формате nginx combined:

Значение API-ключа в журнал не записывается. Служебные предупреждения (неудачная авторизация, превышение лимитов, блокировка) пишутся в основной лог.

Эндпоинты

Все команды ниже вызываются методом GET с заголовком X-API-KEY; исключение - POST /templates/add.

Состояние и версия

GET /state/live

Проверка доступности API. Возвращает 200, если сервер запущен.

Тело ответа пустое: успех определяется кодом 200.

GET /version/build

Возвращает номер сборки в виде простого текста.

Пример ответа: 490 (номер зависит от сборки 2.22.4.490).

GET /version/app

Возвращает версию приложения в виде простого текста.

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

GET /v2/statistics

Возвращает текущую статистику в JSON. Описание полей - на странице API v2.

Плейбуки

GET /play/{id}

Запускает плейбук по идентификатору. Параметр пути id - UUID плейбука.

  • 201 - плейбук запущен.
  • 400 - идентификатор не является UUID.
  • 404 - плейбук не найден.

Тело ответа пустое: успех определяется кодом 201.

GET /playbook/list

Возвращает список плейбуков в виде строк имя=id.

Messages: управление отправкой

GET /messages/start

Запускает отправку событий с текущим профилем. Необязательные параметры:

  • eps - количество событий в секунду;
  • stoptime - время работы в секундах;
  • stopcount - остановка после указанного количества событий.

Тело ответа пустое: успех определяется кодом 200.

  • 200 - отправка запущена.
  • 400 - неверное значение eps.
  • 423 - отправка уже запущена.

GET /messages/stop

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

Тело ответа пустое: успех определяется кодом 200.

  • 200 - отправка остановлена.
  • 423 - отправка не запущена.

GET /messages/eps

Текущее количество событий в секунду.

GET /messages/avg

Средний EPS за период.

GET /messages/sent

Количество отправленных событий.

GET /messages/time

Время работы отправки в секундах.

GET /messages/state

Состояние отправки: active, если отправка идёт, и stop, если остановлена.

GET /messages/set

Изменяет параметры отправки без запуска и остановки. Параметры:

  • eps - новое значение EPS;
  • stoptime - время работы в секундах;
  • stopcount - количество событий до остановки;
  • timeout - пауза между отправками;
  • randomtimeout - случайная пауза (true/false).

Тело ответа пустое: успех определяется кодом 200.

  • 200 - параметры применены.
  • 400 - неверное значение eps.
  • 423 - отправка уже запущена.

GET /messages/clear и /messages/disable

/messages/clear удаляет все правила отправки, /messages/disable отключает их без удаления.

Тело ответа пустое: успех определяется кодом 200.

GET /messages/add

Добавляет правило отправки. Параметры:

  • proto - протокол; по умолчанию UDP;
  • port - порт; по умолчанию 514;
  • host - хост; по умолчанию 127.0.0.1;
  • template - имя шаблона;
  • json - отправка в JSON (true/false), по умолчанию false.

Тело ответа пустое: успех определяется кодом 200.

  • 200 - правило добавлено.
  • 400 - неверный протокол, порт или хост.
  • 403 - недопустимое имя шаблона (Path Traversal).

Профили Messages

/profiles/list возвращает список имён профилей (по одному в строке).

/profiles/save, /profiles/load и /profiles/delete управляют профилем по имени:

Тело ответа пустое: успех определяется кодом 200.

  • Параметр name обязателен, до 128 символов.
  • 400 - имя отсутствует или недопустимо.
  • 423 - отправка запущена; операции с профилями недоступны.

Sender: одиночные события

GET /sender/start

Отправляет одно событие. Параметры:

  • message - сообщение; обязательный параметр;
  • host - хост;
  • port - порт;
  • proto - протокол;
  • index - значение индекса в шаблоне;
  • json - отправка в JSON (true/false).

Тело ответа пустое: успех определяется кодом 200.

  • 200 - событие отправлено.
  • 400 - отсутствует message или неверный хост/порт.

Templates: шаблоны

GET /templates/list

Возвращает список имён шаблонов (по одному в строке).

POST /templates/add

Добавляет событие в шаблон. Предпочтительный метод - POST с телом application/x-www-form-urlencoded. Для обратной совместимости поддерживается и GET с теми же параметрами в query-строке, но GET ограничен длиной request-line (~16 КиБ).

Параметры (в теле POST или в query GET):

  • name - имя шаблона; обязательно, до 64 символов;
  • message - событие; обязательно, до 262 144 байт UTF-8 (256 КиБ);
  • index - индекс в шаблоне (необязательно).

Пример POST:

Пример GET (для коротких событий):

Тело ответа пустое; результат определяется HTTP-кодом.

  • 201 - событие добавлено.
  • 400 - отсутствуют или недопустимы name/message.
  • 403 - недопустимое имя (Path Traversal).
  • 413 - тело POST больше 1 МиБ (проверяется до чтения тела) или message больше 262 144 байт UTF-8.
  • 429 - превышен лимит 10 запросов в минуту.

Ограничения: тело POST - до 1 МиБ; message - до 262 144 байт UTF-8; GET request-line - около 16 КиБ, поэтому большие шаблоны добавляйте через POST.

Настройки: отладка

GET /set/settings

Переключает уровень логирования: ?debug=true устанавливает уровень Debug, ?debug=false возвращает Warn. Это не флаг, а выбор уровня; подробнее - на странице Уровни логирования.

Тело ответа пустое: успех определяется кодом 200.

Версионирование

Версия API входит в путь: команды с префиксом /v2/ относятся к API v2 (см. API v2), команды без префикса - к API v1. Существующие методы и поля не удаляются без предупреждения: изменения публикуются в разделе обновлений.

История изменений

История изменений API публикуется в новостях сайта. Формат записи: версия, дата, категории "Добавлено / Изменено / Исправлено / Безопасность". При обновлении проверяйте:

  • способ передачи ключа - только заголовок X-API-KEY;
  • лимиты запросов и размеры шаблонов;
  • формат ответа /v2/statistics;
  • коды ответов 403, 413, 423, 429, 502.

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

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