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)는 Development 환경에서만 http://<box>:5000/swagger에서
제공됩니다.
추론 서비스에는 자체 인증이 없으므로 릴리스 배포는 50051 포트를 라우팅 가능한
주소로 게시하지 않습니다. 기본 릴리스 compose는 호스트 포트를 전혀 게시하지 않으며,
Jetson 릴리스 compose 파일은 기본값으로 127.0.0.1에만 게시합니다
(AIBOARD_INFERENCE_BIND).
/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 | 페이지네이션된 중앙화 로그(백엔드 + 추론). 선택 필터 correlationId를 지정하면 한 추론 틱의 줄(입력 읽기, 엔진, 모든 출력 쓰기)만 반환 |
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). 대시보드는 이 코드들을 지역화된 메시지로
매핑합니다.