HTTP API

HTTP API является интерфейсом интеграции Beam Bench. Настольное приложение, CLI и любой внешний клиент обращаются к одним и тем же маршрутам. Если вам нужно использовать Beam Bench в среде без CLI (веб-приложение, сервер интеграции, мобильное приложение, собственные инструменты), используйте API напрямую.

API поставляется вместе с настольным приложением и работает внутри его процесса. Устанавливать отдельный сервис не требуется.

Параметры по умолчанию и безопасность

В текущей сборке локальный API-сервер поставляется со следующими настройками:

• Локальный API: выключен.
• Порт API: 5900.
• Разрешить сетевым устройствам подключаться: выключено. При включении API он привязывается к 127.0.0.1 и принимает подключения только с этого компьютера.

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

Чтобы использовать API, измените его настройки в разделе Настройки → Общие:

1. Откройте настольное приложение.
2. Изменить → Настройки → Общие.
3. Включите Локальный API.
4. Оставьте параметр Разрешить сетевым устройствам подключаться выключенным, если подключение другого доверенного устройства не требуется.

Изменения вступают в силу немедленно, перезапуск не требуется.

Базовый URL

http://<host>:5900/api/v1

При выключенном параметре Разрешить сетевым устройствам подключаться значение <host> равно localhost (или 127.0.0.1). Если параметр включен, сервер доступен по локальному IP-адресу компьютера с любого устройства в сети.

Порт можно настроить в разделе Настройки → Общие; 5900 является значением по умолчанию.

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

Отсутствует. У API нет токена, ключа или входа в систему.

• При привязке к localhost границей доступа служит модель доступа на уровне ОС: любой процесс на вашем компьютере может обращаться к API.
• При включенной привязке к сети любой пользователь в той же сети может обращаться к API. Не используйте режим сетевой привязки в недоверенной сети Wi-Fi.

Формат запроса

Тела всех запросов POST/PATCH/PUT имеют формат JSON:

Content-Type: application/json

Строки запроса имеют плоский формат key=value. Сегменты пути кодируются в URL стандартным образом.

Оболочка ответа

Успешные ответы возвращают тело ресурса напрямую, без оболочки:

{
  "field": "value",
  "...": "..."
}

Ошибки возвращают унифицированную оболочку:

{
  "error": {
    "code": "InvalidInput",
    "message": "Human-readable summary of what went wrong.",
    "details": { "...optional structured context..." }
  }
}

error.code может иметь одно из значений:

Ошибки, требующие подтверждения

Небольшой набор операций может перемещать станок или включать лазер. Для таких конечных точек требуется явно указанный флаг подтверждения в теле запроса. Если флаг отсутствует, API возвращает 428 Precondition Required:

{
  "error_code": "CONFIRMATION_REQUIRED",
  "missing": ["confirm_motion"],
  "message": "This command can move the machine and requires explicit confirmation."
}

Повторно отправьте запрос, установив названный флаг в true. В настоящее время используются флаги confirm_motion, confirm_laser_on, confirm_raw_gcode и confirm_air_assist.

Группы конечных точек

Справочные страницы отдельных ресурсов еще в разработке; пока используйте схему возможностей агента.

Просмотр доступных возможностей

Самый быстрый способ узнать, что доступно в установленной версии:

curl -s http://localhost:5900/api/v1/agent/capabilities | jq .

Команда возвращает полную схему возможностей, включая все конечные точки, их параметры и структуру ответов. Схема является авторитетным описанием, а эта страница служит руководством по ней.

Для просмотра состояния:

curl -s http://localhost:5900/api/v1/agent/state | jq .

Чтобы получить текстовое руководство по управлению приложением:

curl -s http://localhost:5900/api/v1/agent/guide

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

Все маршруты находятся в /api/v1. При появлении обратно несовместимых изменений они будут добавляться в /api/v2. Дополнительные изменения (новые конечные точки, новые необязательные поля) выпускаются в v1 без изменения версии.

Связанные материалы

• Руководство по использованию HTTP API: введение в формате учебника с рабочими примерами.
• Как CLI и приложение используют общее состояние: модель согласованности, лежащая в основе этих конечных точек.
• Настройки → Общие: где включить API и выбрать порт.