База знаний

Документация по API  Распечатать статью

Stormwall API

API позволяет управлять объектами в рамках заказанных услуг - добавление и удаление доменов, обновление параметров конфигураций, выборка истории атак и т.п. Данная документация предоставляет общую информацию о командах с примерами и описанием возможных ошибок и проблем. Более подробное описание команд и моделей данных для запросов и ответом можно посмотреть по следующим адресам:

API использует REST-интерфейс и только встроенные HTTP функции, которые понимает любой стандартный HTTP клиент. 

Для удобства проксирования и мониторинга передача идентификационных данных одного объекта всегда использует часть пути. Например, GET /user/service/1/domain/2 - где 1 - это идентификатор услуги, а 2 - идентификатор домена

Для передачи списка в командах чтения используются параметры запроса с повторяющимся ключом. Например,  GET /user/service/1/domain/stats?domain_id=3&domain_id=6

Все остальные данные для модифицирующих команд передаются через “тело” запроса в формате JSON. Ответ всегда приходит в формате JSON, в том числе и для ошибок, за исключением команд конвертации. Максимальный размер “тела” запроса - 1 Мб. Максимальный размер заголовков - 8 Кб.

Для индикации ошибок в системе определено два уровня информации - HTTP статус и список кодов в ответе. HTTP статус, отличный от “200”, указывает на “фатальную” ошибку со стороны пользователя или внутри системы. При HTTP статусе “200” список ошибок указывает на “мягкие” ошибки.

Если API вернул “фатальную” ошибку, то система еще не начала производить никакие действия с объектами в рамках услуг и можно повторить запрос, возможно со скорректированными данными. Например, если команда ожидает имя домена, а на вход подается строка, которая не является корректным именем домена, допустим, с пробелами, то в ответ придет ошибка “400”, указывающая на некорректность входных данных.

Если API вернул хотя бы одну запись в списке “мягких” ошибок, то это означает, что система уже стала проводить операции с объектами, возможно даже на “железе” и формально входные данные корректны, но для некоторых подсистем они не являются правильными или их нельзя применить именно в данный момент. Эти ошибки можно исправить путем выполнения дополнительных команд, но они не приведут к некорректной работе объекта в текущем состоянии. Например, установка сертификата SSL может возвратить “мягкую” ошибку, указывающую на то, что формально входные данные соответствуют правильному сертификату, но система отказалась его устанавливать именно для данного домена, так как его имя не соответствует записям в сертификате. К “мягким” ошибкам также можно отнести предупреждения от системы. Например, если на данный момент некоторые процессы обработки объекта в системе поставлены в очередь и будут завершены в ближайшее время.

Для простоты принято следующее отображение методов HTTP в действия над объектами:

  • Создание нового объекта - POST

  • Получение информации об объекте - GET

  • Обновление информации объекта - PUT

  • Удаление объекта - DELETE



Статусы HTTP ответов

  • 200 - запрос выполнился успешно

  • 400 - некорректные входные данные команды

  • 403 - команда или входные данные недопустимы для указанного токена

  • 404 - команда не определена в системе

  • 405 - метод не применим к данной команде

  • 501 - данная команда находится в разработке

  • 503 - функционал системы на данный момент недоступен или превышен лимит по количеству запросов в секунду

Все остальные коды 500 указывают на проблемы на стороне системы.

Поля ответа для “фатальных” ошибок:

 

Имя поля

Тип поля

Описание поля

statusCode

Число

Числовое представление HTTP статуса 

error

Строка

Строковое представление HTTP статуса

message

Строка

Описание причины ошибки

Пример: { "statusCode": 400, "error": "Bad Request", "message": "Invalid request params input" }

 

Поля ответа со списком “мягких” ошибок - error_list:

Имя поля

Тип поля

Описание поля

type

Число

Группа, к которой относится ошибка

code

Строка

Код ошибки

Пример: { "error_list": [{ "type": "SSL", "code": "INVALID_CERT_KEY_PAIR" }] }

 

Для определения значений флагов в командах всегда используются целые числа 0 и 1, и никогда не используется JSON булевый тип данных.

Все команды, которые возвращают списки элементов, могут содержать следующие поля:

Имя поля

Тип поля

Описание поля

list

Массив

Список элементов

total_count

Число

Общее количество элементов в базе по текущему фильтру

max_count

Число

Максимально возможное количество элементов в базе

offset

Число

Смещение первого элемента набора данных ответа от начала отфильтрованного списка

limit

Число

Максимальный размер набора данных для одного ответа

count

Число

Полученное количество элементов

Пример: 

{ "list": [{  "attack_id": "ABC", "attack_target": "1.1.1.1" }], "offset": 10, "limit": 10, "total_count":  100 }

 

Для основной части команд требуется авторизация в виде указания API токена. Передача API токена производится с помощью заголовка Cookie с именем api_access_token.

Пример:

curl -XGET --cookie "api_access_token=eyJhb...s" https://api.stormwall.pro/user/service-list

Для создания API токена необходимо зайти на страницу управления токенами в профиле пользователя и нажать на кнопку “Добавить новый токен”:



Новый токен будет представлен в отдельной закладке на этой же странице. Для каждого токена назначается его уникальный ключ - subject, по которому можно идентифицировать, например, в журнале запросов, какие команды были выполнены с указанным токеном.

Для каждого API токена определена дата истечения срока, после которой команды начнут выдавать ошибку “401” при использовании указанного токена.

Для того, чтобы скопировать значение токена, необходимо нажать на “глаз” возле многострочного текстового поля. 

Предупреждение: В целях безопасности API токен можно отозвать до истечения срока годности, но удалить можно только после указанного в токене времени. Если суммарное количество отозванных и активных токенов достигнет максимально возможного количества (указывается на странице), то не будет возможности создать дополнительные токены в течении минимального срока годности среди активных и отозванных токенов.

При создании нового API токена все токены с истекшей датой будут автоматически удалены из системы, так как они больше не представляют опасности.

Для быстрой проверки работы API и генерации curl команд можно воспользоваться страницей документации и кнопкой “Try it out!” в каждом описание команды. Для этого необходимо авторизоваться на сайте и перейти на страницу управления токенами. В данном случае будет действовать сессионный токен, с помощью которого и будет происходить авторизация в API командах.

Затем в отдельной закладке открыть документацию API. В поле cookie нужно вписать значение активного токена api_access_token=eyJhb…, если необходима правильная генерация curl строки. После заполнения всех остальных параметров команды, ее можно выполнить с помощью кнопки “Try it out!”.

Если через некоторое время при выполнении команды вернулся код ошибки - 401, то необходимо продлить сессионный токен для документации путем простой перезагрузки страницы со списком токенов на отдельной закладке или нажать на кнопку “Обновить токен документации”.



Curl строка генерируется для Linux систем. В системе Windows все символы ‘(single quote) надо заменить на “ (double quote) и экранировать этот символ внутри данных либо воспользоваться Linux-like терминалом, например, “Git Bash”.

В документации API для каждой команды для результата и для “сложных” параметров можно посмотреть их модель данных, переключившись на закладку “Model”. В моделях указан тип полей и их краткое описание.

 

 

 

Помог ли вам данный ответ?