API HTTP

A API HTTP é a interface de integração do Beam Bench. A maioria dos comandos da CLI e dos clientes externos usa estas rotas. O frontend para desktop chama o serviço compartilhado por meio do IPC do Tauri e não precisa do servidor HTTP para o uso normal. Se você tiver um caso de uso que precise do Beam Bench em um ambiente que não seja a CLI, como um aplicativo web, servidor de integração, aplicativo móvel ou suas próprias ferramentas, use a API diretamente.

A API é distribuída com o aplicativo para desktop e executada no processo. Não há um serviço separado para instalar.

Padrões e segurança

Na compilação atual, o servidor de API local é distribuído com estas configurações:

• API local: desativada.
• Porta da API: 5900.
• Permitir dispositivos de rede: desativada. Quando a API está ativada, ela é vinculada a 127.0.0.1 e aceita conexões somente deste computador.

A API não escuta conexões até que você opte por ativá-la. Ativar o acesso à rede é uma opção separada porque a API não tem autenticação e inclui operações que podem mover a máquina e disparar o laser.

Para usar a API, altere suas configurações em Configurações → Geral:

1. Abra o aplicativo para desktop.
2. Editar → Configurações → Geral.
3. Ative API local.
4. Mantenha Permitir dispositivos de rede desativada, a menos que outro dispositivo confiável precise se conectar.

As alterações entram em vigor imediatamente, sem necessidade de reiniciar.

URL base

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

<host> é localhost ou 127.0.0.1 quando Permitir dispositivos de rede está desativada. Quando ela está ativada, o servidor pode ser acessado pelo IP da LAN da máquina a partir de qualquer dispositivo na rede.

A porta pode ser configurada em Configurações → Geral; 5900 é o padrão.

Autenticação

Nenhuma. A API não tem token, chave ou login.

• Com a vinculação ao localhost, o modelo de acesso no nível do sistema operacional é o limite: qualquer processo no seu computador pode se comunicar com a API.
• Com a vinculação à rede ativada, qualquer pessoa na mesma rede pode se comunicar com a API. Não use o modo de vinculação à rede em uma rede Wi-Fi não confiável.

Formato da solicitação

Todos os corpos POST/PATCH/PUT são JSON:

Content-Type: application/json

As strings de consulta são pares simples de chave=valor. Os segmentos do caminho são codificados como URL normalmente.

Envelope da resposta

As respostas bem-sucedidas retornam o corpo do recurso diretamente, sem um invólucro:

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

Os erros retornam um envelope uniforme:

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

error.code é um dos seguintes:

Erros que exigem confirmação

Um pequeno conjunto de operações pode mover a máquina ou disparar o laser. Esses endpoints exigem um sinalizador de confirmação explícito no corpo da solicitação. Se ele estiver ausente, a API retornará 428 Precondition Required:

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

Envie a solicitação novamente com o sinalizador indicado definido como true. Os sinalizadores atualmente usados são confirm_motion, confirm_laser_on, confirm_raw_gcode e confirm_air_assist.

Edições simultâneas de projetos

As transações de Design comparam o projeto capturado no momento da confirmação. Uma edição simultânea, troca de projeto ou fechamento pode retornar stale_revision. Atualize o estado e reavalie a alteração antes de tentar novamente. Não reproduza cegamente um snapshot de projeto antigo sobre um trabalho mais recente.

Grupos de endpoints

As páginas de referência por recurso ainda estão em desenvolvimento; enquanto isso, consulte o esquema de recursos do agente.

Descobrir a interface ativa

A maneira mais rápida de ver o que sua versão instalada disponibiliza:

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

Isso retorna o esquema completo de recursos, incluindo cada endpoint, seus parâmetros e o formato da resposta. O esquema é a descrição oficial; esta página serve como guia.

Para inspecionar o estado:

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

Para obter uma orientação escrita sobre como controlar o aplicativo:

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

Versionamento

Todas as rotas estão em /api/v1. Alterações incompatíveis vão para /api/v2 quando ocorrerem. Alterações aditivas, como novos endpoints e novos campos opcionais, são distribuídas em v1 sem aumento de versão.

Relacionado

• Guia de uso da API HTTP: uma introdução em formato de tutorial com exemplos completos.
• Como a CLI e o aplicativo compartilham o estado: o modelo de consistência por trás desses endpoints.
• Configurações → Geral: onde ativar a API e escolher a porta.