Справочник по API
BlankTrail Proxy предоставляет локальный HTTP API, с помощью которого вы можете открывать порты, настраивать идентичности и автоматизировать всё, что делает дашборд. На этой странице описаны базовый URL, аутентификация и соглашения.
Базовый URL
Все эндпоинты находятся под префиксом /api/v1 на том же хосте и порту, что и дашборд:
http://127.0.0.1:8891/api/v1API и дашборд используют один и тот же источник (origin), поэтому вызовы из ваших собственных скриптов и инструментов работают сразу и без дополнительной настройки.
Аутентификация
API работает по принципу «запрещено по умолчанию»: почти каждый эндпоинт требует аутентификации. Есть два способа аутентификации:
- API-ключ — передавайте его в заголовке X-API-Key. Лучший вариант для скриптов и автоматизации.
- Сессионная cookie — получается при входе в систему; используется веб-дашбордом.
Найти и заменить свой API-ключ можно в диалоге «Настройки» дашборда. Передавайте его в каждом запросе:
curl -H "X-API-Key: YOUR_API_KEY" http://127.0.0.1:8891/api/v1/statusВажноAPI-ключ даёт полный контроль над вашими портами. Храните его в секрете и ограничьте сетевой доступ к порту дашборда (привяжите его к localhost или используйте SSH-туннель на серверах).
Соглашения
- Запросы и ответы — в формате JSON. В запросах с телом отправляйте Content-Type: application/json.
- Конфигурация всегда передаётся в теле JSON, а не в строке запроса.
- API версионируется под префиксом /api/v1. Несовместимые изменения будут вынесены в новый префикс версии.
Коды состояния
| Код | Значение |
|---|---|
| 200 OK | Успех. |
| 202 Accepted | Принято и обрабатывается (например, было запущено обновление). |
| 400 Bad Request | Некорректный ввод, отсутствующее поле или недопустимое значение. |
| 401 Unauthorized | Требуется аутентификация, но она отсутствовала или была недействительной. |
| 404 Not Found | Ресурс не существует (например, порт не открыт). |
| 409 Conflict | Конфликт — например, порт уже открыт или шлюз используется. |
| 429 Too Many Requests | Превышен лимит запросов; снизьте частоту и повторите попытку. |
| 500 Internal Server Error | Непредвиденная ошибка. |
Справочник по темам
- Порты и трафик — открытие, закрытие, получение списка и настройка портов; тестирование вышестоящего прокси.
- Профили и маршрутизация — идентичности, пресеты, правила доменов и шлюзы.
- Пулл портов — открытие пуллов портов из списка прокси и управление ими.
- Лицензия и доступ — статус лицензии, аутентификация и CA-сертификат.