Программный интерфейс API
АРХИВА предоставляет REST API версии 3 — единый программный интерфейс для интеграций: SIEM-системы, HelpDesk, GRC, автоматизации ввода-вывода и собственных сценариев. Через API доступны те же операции, что и через интерфейс: поиск, действия над выборкой, экспорт, импорт, конфигурация, состояние, аудит, аналитика и граф переписки.
Открытая спецификация
Полная и актуальная для вашей установки спецификация доступна на самом сервере:
Спецификация точнее любого описания: она соответствует версии установленного сервера, содержит схемы запросов и ответов и позволяет сразу сгенерировать клиентский код.
Базовый адрес и группы
Единый префикс: https://<сервер-архива>/api/v3.
Группа | Назначение |
|---|---|
| Вход, выход, состояние сессии, двухфакторная регистрация |
| Мастер первичной настройки (только до первого входа) |
| Разделы конфигурации: домены, тома, подключения, правила, роли, настройки поиска и т.д. |
| Состояние системы, тома, процессы |
| Поиск, сессии поиска, заморозка выборки, массовые действия (удержание, удаление, экспорт, пересылка, метки) |
| Чтение сообщений и вложений |
| Поиск по журналу аудита |
| Аналитика |
| Построение социального графа переписки |
| Метки |
| Пользовательские настройки |
| Импорт: возобновляемая закачка, каталог, подключения |
Аутентификация
API работает поверх сессии АРХИВА: клиент выполняет вход через группу /auth (логин/пароль, поддерживаются все настроенные способы входа), и последующие запросы выполняются с cookie сессии. На каждую операцию сервер проверяет право доступа роли — независимо от того, что интерфейс скрыл недоступные элементы. Роль без права получает 403.
Соглашения
Коды ответов предсказуемы — интеграция может принимать решения по коду, не разбирая тело:
Код | Значение |
|---|---|
| Выполнено, результат в теле |
| Создано (например, замороженная выборка) |
| Принято как фоновая задача — дальше наблюдайте по |
| Выполнено без тела (синхронные операции с томами) |
| Некорректный запрос |
| Не аутентифицирован |
| Нет права (в том числе чужая выборка, отсутствие лицензии) |
| Ресурс не найден — в том числе любой запрос, не совпавший ни с одной операцией API |
| Состояние изменилось (выборка «уехала», число совпадений не совпало с подтверждённым) |
| Превышен лимит (например, выборка больше допустимого размера) |
| Служба временно недоступна (внешнее хранилище отвечает |
| Не хватает места в хранилище |
Массовые операции (удержание, удаление, экспорт, пересылка, метки) над большой выборкой отвечают 202 с идентификатором задачи; прогресс и счётчики читаются по процессам. Порог «сразу или фоном» определяет сервер.
Защита от повторной отправки. Необратимые массовые операции поддерживают заголовок Idempotency-Key: повторный запрос с тем же ключом не выполняет действие повторно, а возвращает результат первого выполнения. Используйте ключ при любых запросах, которые могут быть отправлены повторно из-за сбоя сети.
Сессии поиска. Поиск возвращает токен сессии; по нему читаются страницы результатов, замораживается выборка (POST /search/{token}/freeze) и выполняются действия. Токен даёт доступ только к собственному поиску: чужой, истёкший или освобождённый токен отвечает 404. Глубокие страницы результатов открываются без замедлений: переход вглубь выдачи стоит столько же, сколько вторая страница.
Пример: поиск и заморозка выборки
Точные схемы запросов — в открытой спецификации /api-docs/.
Связанные темы
Юридическая работа с архивом — заморозка выборки, удержание, защита от повторной отправки.
Роли — права, которые проверяет API.
SSL — настройка HTTPS для сервера.