HTTP API

모든 HTTP 클라이언트에서 Beam Bench를 제어할 수 있습니다. CLI가 통신하는 것과 동일한 인터페이스입니다.

HTTP API는 Beam Bench의 통합 인터페이스입니다. 데스크톱 앱, CLI 및 모든 외부 클라이언트가 동일한 경로를 통해 통신합니다. 웹 앱, 통합 서버, 모바일 앱 또는 자체 도구 등 CLI가 아닌 환경에서 Beam Bench를 사용해야 하는 경우 API를 직접 사용하십시오.

API는 데스크톱 앱에 포함되어 프로세스 내에서 실행됩니다. 별도로 설치해야 하는 서비스는 없습니다.

기본값 및 보안

현재 빌드의 로컬 API 서버에는 다음 설정이 적용됩니다.

로컬 API: 꺼짐.
API 포트: 5900.
네트워크 장치 연결 허용: 꺼짐. API가 활성화되면 127.0.0.1에 바인딩되며 이 컴퓨터에서만 연결을 수락합니다.

API는 사용자가 활성화하기 전까지 연결을 수신하지 않습니다. API는 인증되지 않으며 장치를 움직이고 레이저를 발사할 수 있는 작업을 포함하므로 네트워크 액세스 활성화는 별도의 명시적 동의 절차입니다.

API를 사용하려면 설정 → 일반에서 설정을 변경하십시오.

데스크톱 앱을 엽니다.
편집 → 설정 → 일반을 선택합니다.
로컬 API를 켭니다.
신뢰할 수 있는 다른 장치를 연결해야 하는 경우가 아니라면 네트워크 장치 연결 허용을 꺼진 상태로 둡니다.

변경 사항은 즉시 적용되며 다시 시작할 필요가 없습니다.

기본 URL

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

네트워크 장치 연결 허용이 꺼져 있으면 <host>는 localhost 또는 127.0.0.1입니다. 이 옵션을 켜면 네트워크의 모든 장치에서 해당 컴퓨터의 LAN IP로 서버에 연결할 수 있습니다.

포트는 설정 → 일반에서 구성할 수 있으며 기본값은 5900입니다.

인증

없습니다. API에는 토큰, 키 또는 로그인이 없습니다.

localhost 바인딩을 사용하는 경우 OS 수준의 액세스 모델이 경계가 됩니다. 컴퓨터의 모든 프로세스가 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에는 다음 값 중 하나가 사용됩니다.

코드	HTTP	의미
`NotFound`	404	요청한 리소스가 존재하지 않습니다.
`InvalidInput`	400	요청 본문 또는 매개변수의 형식이 잘못되었거나 거부되었습니다.
`InvalidState`	412	앱이 이 작업을 수행할 수 있는 상태가 아닙니다(예: 열린 프로젝트가 없음).
`Busy`	409	충돌하는 작업이 이미 진행 중입니다.
`Conflict`	409	마지막으로 읽은 후 다른 작성자가 리소스를 변경했습니다.
`StaleRevision`	412	수정 토큰이 현재 토큰보다 이전 버전입니다. 다시 읽고 재시도하십시오.
`MachineIo`	502	장치 연결에 실패했습니다(연결 끊김, 시간 초과, 전송 오류).
`Persistence`	500	디스크 쓰기 또는 읽기에 실패했습니다.
`Internal`	500	예기치 않은 서버 오류입니다. 버그로 보고하십시오.

확인이 필요한 오류

장치를 움직이거나 레이저를 발사할 수 있는 일부 작업은 요청 본문에 명시적인 확인 플래그가 필요합니다. 플래그가 없으면 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입니다.

엔드포인트 그룹

경로	범위
`/api/v1/app`	앱 수준 정보: 버전, 가동 시간, 기능입니다.
`/api/v1/agent`	에이전트 기능 스키마, 상태 스냅샷 및 운영 안내입니다.
`/api/v1/projects`	열기, 저장, 닫기입니다. 레이어, 객체, 실행 취소 및 다시 실행입니다.
`/api/v1/projects/import`	SVG, DXF, PDF, AI 및 래스터 이미지를 프로젝트로 가져옵니다.
`/api/v1/export`	프로젝트를 SVG, DXF, PDF, EPS, AI로 렌더링합니다.
`/api/v1/design`	현재 디자인을 설명하고, PNG로 렌더링하며, 트랜잭션 방식으로 편집 사항을 적용합니다.
`/api/v1/preview`	절단 미리보기 및 통계를 생성합니다.
`/api/v1/jobs`	사전 검사, 실행, 드라이런, 일시 중지, 재개, 프레임 및 중지입니다.
`/api/v1/machine`	연결, 연결 해제, 상태, 조그 및 원점 복귀입니다.
`/api/v1/camera`	장치, 상태, 캡처, 오버레이(표시, 변환, 렌더링), 보정 및 정렬입니다.
`/api/v1/console`	원시 G-code를 전송합니다. 최근 콘솔 로그를 읽습니다.
`/api/v1/macros`	사용자 매크로를 나열하고 저장하고 실행합니다.
`/api/v1/materials`	재료 라이브러리: 재료와 두께를 기준으로 하는 프리셋입니다.
`/api/v1/profiles`	장치 프로필: 생성, 나열 및 적용입니다.
`/api/v1/assets`	아트 라이브러리 자산에 액세스합니다.
`/api/v1/vector`	벡터 작업: 변환, 부울 연산, 그룹 및 경로입니다.
`/api/v1/events`	상태 변경 및 장치 이벤트의 WebSocket 스트림입니다.

리소스별 참조 페이지는 현재 작성 중입니다. 그동안에는 에이전트 기능 스키마를 참조하십시오.

현재 API 확인

설치된 버전에서 제공하는 항목을 확인하는 가장 빠른 방법은 다음과 같습니다.

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에 포함됩니다.