API 개요
백엔드는 5000 포트에 두 개의 REST 표면을 노출하며, 여기에 더해 gRPC 서비스와 SignalR 허브를 제공합니다:
| 표면 | 기본 경로 | 인증 | 대상 |
|---|---|---|---|
| 내부 API | /api/… | JWT 베어러(로그인 세션) | 대시보드 UI. 박스 내 스크립팅에도 사용 가능 |
| 외부 API | /api/external/v1/… | X-AiBoard-ApiKey 헤더 | 서드파티 통합(SCADA, 히스토리안) |
| gRPC 추론 | 포트 50051 | 없음(내부 네트워크 전용) | 백엔드 ↔ 추론 런타임 |
| SignalR 허브 | /hub/realtime | JWT (?access_token=) | 라이브 대시보드 업데이트 |
모든 내부 엔드포인트는 기본적으로 인증을 요구합니다(기본 거부 정책). POST /api/auth/login과
GET /api/system/health만 익명입니다. 두 가지 역할이 존재합니다: admin(전체 제어)과
viewer(읽기 전용 대시보드). 대화형 API 문서(Swagger UI)는 http://<box>:5000/에서
제공됩니다.
/api/auth/login 사용자명/비밀번호를 JWT(8시간 수명)로 교환합니다. 실패한 로그인은 IP당 속도 제한됩니다(60초당 5회).
Authorization: Bearer <jwt>리프레시 토큰은 없습니다 — 토큰이 만료되면 다시 로그인하세요. GET /api/auth/me는 토큰 뒤의
신원을 반환합니다. 관리자 계정은 설치 시 번들 설치 프로그램(seed-admin)이 생성합니다. 기본
자격 증명은 없습니다.
내부 API 맵
섹션 제목: “내부 API 맵”데이터소스
섹션 제목: “데이터소스”입력(읽기 경로)과 출력(쓰기 경로) 데이터소스는 /api/datasources/input과
/api/datasources/output 아래에서 별도로 관리됩니다 — 둘 다 관리자 전용입니다. 각각 동일한
수명 주기를 지원합니다:
| 동사 + 경로(상대) | 목적 |
|---|---|
GET / · GET /{id} | 목록 / 상세(비밀 필드는 ***로 마스킹) |
POST / · PUT /{id} · DELETE /{id} | 생성 / 수정 / 삭제 |
GET /plugins · GET /plugins/{type}/schema | 사용 가능한 프로토콜 플러그인 + 해당 구성 폼 스키마 |
POST /test-connection · POST /{id}/test-connection | 도달 가능성 프로브 |
POST /{id}/tags · POST /{id}/browse-tags | 태그 매핑 교체 / 장치에 태그 목록 요청 |
데이터소스는 순수한 연결 관리입니다: 무엇이 존재하고 어떻게 도달하는지. 어떤 입력에
어떤 모델이 실행되는지, 그리고 어떤 파이프라인이 동작 중인지는 플로우에 속합니다 —
아래 표를 참조하세요. 출력 데이터소스는 추가로 POST /{id}/test-write를 지원합니다 —
출력 데이터소스를 참조하세요.
플로우
섹션 제목: “플로우”기본 경로 /api/flows. 플로우는 입력 데이터소스 하나, 모델 버전 하나, 그리고 임의 개수의
출력 데이터소스를 묶습니다. 플로우가 곧 페어링이며, 플로우를 활성화하는 것이 파이프라인을
준비시키는 행위입니다.
| 동사 + 경로(상대) | 용도 |
|---|---|
GET / · GET /{id} | 목록 / 상세 |
POST / · PUT /{id} · DELETE /{id} | 생성 / 수정 / 삭제 |
POST /{id}/enable | 이 플로우를 Ready로 준비(본문 { "enabled": true | false }) |
동시에 활성화될 수 있는 플로우는 최대 하나이며, 하나를 활성화하면 이전 것은 해제됩니다.
활성화된 플로우를 수정하면 409 disable_flow_first를 반환합니다 — 동작 중인 파이프라인을
그 아래에서 바꿔치기하지 않습니다.
활성화는 플로우를 Ready로 만들 뿐 스트리밍을 시작하지 않습니다. 시작은 여전히
POST /api/inference/start이며, “어떤 플로우가 선택되었는가”와 “스트리밍 중인가”는
별개의 사실로 유지됩니다.
/api/models 모든 모델 버전을 나열합니다(인증된 모든 사용자).
/api/models/upload .onnx 파일을 업로드합니다(관리자). 추론 런타임을 통해 검증되며, 버전은 불변입니다.
/api/models/{modelId}/activate/{version} 버전을 활성화합니다(관리자).
/api/models/{modelId}/rollback 이전의 유효한 버전을 재활성화합니다(관리자).
그 외: GET /{modelId}/active, GET /{modelId}/history,
DELETE /{modelId}/{version}, DELETE /{modelId}/cleanup(오래된 버전 정리, 유지 개수 구성
가능).
추론 수명 주기 및 관측성
섹션 제목: “추론 수명 주기 및 관측성”/api/inference/status 현재 상태: idle / ready / running, 활성 데이터소스, 로드된 모델.
/api/inference/start 스트리밍을 시작합니다(관리자). 데이터소스가 Ready가 아니면 409.
/api/inference/stop 스트리밍을 우아하게 중지합니다 — 버퍼링된 예측이 먼저 출력 싱크로 배출됩니다(관리자).
/api/inference/stats Inference Stats 페이지에 공급되는 지연 시간 집계.
/api/inference/backpressure 핫 패스 카운터: 드롭, 싱크 차단, 채널 깊이. 시작 이후 단조 증가.
그 외: GET /api/inference/predictions/recent,
GET /api/inference/payloads/{requestId}, 그리고 /api/inference/thresholds 아래의 모델별
지연 시간 경보 임계값(PUT/DELETE 관리자).
시스템, 로그, 환경설정
섹션 제목: “시스템, 로그, 환경설정”| 엔드포인트 | 목적 |
|---|---|
GET /api/system/health (익명) | 라이브니스 — Docker 헬스체크에 사용 |
GET /api/system/status · GET /api/system/metrics | 런타임 상태. CPU/GPU/메모리 메트릭 |
GET /api/logs | 페이지네이션된 중앙화 로그(백엔드 + 추론) |
GET/PUT /api/dashboard/layout | 사용자별 대시보드 레이아웃 |
GET/PUT/DELETE /api/me/preferences | 사용자별 환경설정 blob |
관리자: 구성 가져오기/내보내기
섹션 제목: “관리자: 구성 가져오기/내보내기”/api/admin/inference-config/export 파이프라인 전체 — 데이터소스, 태그 매핑, 플로우 — 를 하나의 버전 관리된 JSON 엔벨로프로 내보냅니다(비밀은 마스킹).
/api/admin/inference-config/import 엔벨로프를 트랜잭션 방식으로 가져옵니다 — 항목 하나라도 실패하면 파일 전체가 롤백됩니다. 모드: merge(기본) 또는 replace.
외부 API
섹션 제목: “외부 API”서드파티 시스템을 위해 설계되었습니다. API 키가 존재할 때까지 인증 측면에서 비활성화됩니다.
키는 박스 CLI(issue-api-key)에서 발급되고, 한 번만 표시되며, 폐기 가능합니다
(list-api-keys, revoke-api-key). 요청은 속도 제한됩니다(클라이언트당 60초당 100회).
X-AiBoard-ApiKey: ak_<your-key>/api/external/v1/predictions/latest 가장 최근 예측: 출력 값, 신뢰도, 모델 버전, 윈도우 타임스탬프.
/api/external/v1/predictions/history?limit=&offset= 최근 예측(인메모리, 약 1시간 보존, limit ≤ 1000). 추론이 중단된 동안 503.
오류 형식
섹션 제목: “오류 형식”검증 실패는 기계 판독 가능한 코드와 함께 HTTP 400을 반환합니다(예: name_already_exists,
shape_mismatch, model_not_paired, config_invalid:port:range). 수명 주기 충돌은 409를
반환합니다(not_ready, version_exists). 대시보드는 이 코드들을 지역화된 메시지로
매핑합니다.