API — инструкция по использованию

Что такое API?

API — интерфейс прикладного программирования. Этот интерфейс позволяет двум приложениям взаимодействовать друг с другом, используя заранее определенные наборы команд.

API позволяет управлять объектами в рамках заказанных услуг — добавление и удаление доменов, обновление параметров конфигураций, выборка истории атак и т.п. С помощью этого взамодействия вы также можете получать или добавлять информацию в личный кабинет, автоматически извлекать оттуда списки услуг, «черные» и «белые» списки пользователей и многое другое.

Подробное описание команд и моделей данных для запросов и ответов можно посмотреть по следующим адресам:

StormWall API v1 — https://api.stormwall.pro/documentation
StormWall API v2 — https://apiv2.stormwall.pro/swagger-public

Как создать токен?

Для обеспечения безопасного доступа к информации из вашего личного кабинета, реализована аутентификация на основе токенов.
При запросе информации с вашего устройства, оно будет авторизовано при помощи токена аутентификации так же, как вы при использовании логина и пароля для входа в свой личный кабинет.
При создании нового токена вы получаете два значения — срок годности первого составляет 30 дней, второго — 60 дней. Обязательно сохраните сгенерированные значения.

Для создания токена выберите пункт «Управление токенами клиента» в личном кабинете.

На открывшейся странице нажмите на кнопку «Добавить новый токен».

Заполните поле с описанием токена и нажмите на кнопку «Готово».

Скопируйте полученные значения, чтобы сохранить их. Нажмите на кнопку «Закрыть».

После создания токена, он появится в вашем личном кабинете.

По ссылкам в правом верхнем углу вы можете открыть документацию API с примерами запросов.

Обратите внимание — на одном из ресурсов необходимо пройти авторизацию для тестирования запросов на своём личном кабинете.

Каждый токен можно удалить или перевыпустить, а также каждый имеет уникальный ID, по которому можно идентифицировать, например, в журнале запросов, какие действия были выполнены с данным токеном (создание, удаление, рефреш).

Для каждого токена определена дата истечения срока, после которой команды начнут выдавать ошибку “401”/»403″ при его использовании. Время жизни токена — 3 месяца, для рефреш токена — 6 месяцев. Однако, вы можете перевыпустить токен через ЛК либо через эндпоинт 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» }] }

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

Начните работу с API с создания токена.

Для проверки запросов можно открыть любой эндпоинт в swagger документации и в поле cookie вписать значение активного токена api_access_token=eyJhb… После заполнения всех остальных параметров эндпоинта можно нажать кнопку «Try it out», которая сгенерирует curl строку запроса.

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

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

Если у вас возникли трудности с использованием API, пожалуйста, обратитесь в службу поддержки — через чат на сайте или форму обращения в личном кабинете.