REST API

14.1 기본 정보

항목	값
Base URL	http://127.0.0.1:8080/api/v1
인증	Authorization: Bearer {JWT}
CSRF	쿠키 세션 미사용. X-CSRF-Token 헤더 없음
Content-Type	application/json
압축	gzip (Accept-Encoding: gzip)
CORS	화이트리스트 기반
ETag/304 (v1.0)	조건부 캐싱 (If-None-Match)
페이지네이션 (v1.0)	X-Total-Count + Link: <url>; rel="next"
Correlation ID (v1.0)	요청/응답 UUID (X-Correlation-Id)

14.2 per-endpoint Rate Limit (v1.0)

엔드포인트별로 Rate Limit을 차등 적용:

엔드포인트	제한
POST /auth/token	60/분
GET /metrics	3,600/시간
GET /vms	600/분
POST /vms	60/분
기타	600/분 (IP 기본)

14.3 per-method 타임아웃 (v1.0)

유형	타임아웃
읽기 (GET)	8초
쓰기 (POST/PUT)	30초
장기 작업 (migrate, backup)	60초

14.4 주요 엔드포인트

인증

# 토큰 발급
curl -s -X POST http://127.0.0.1:8080/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"<configured-admin-password>"}'
# → {"access_token":"eyJ...", "refresh_token":"eyJ..."}

# 토큰 갱신
curl -s -X POST http://127.0.0.1:8080/api/v1/auth/refresh \
  -d '{"refresh_token":"eyJ..."}'

VM 관리

# VM 목록
curl -s -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8080/api/v1/vms

# VM 생성
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"web-prod",
    "vcpu":4,
    "memory_mb":8192,
    "disk_size_gb":50,
    "os_variant":"ubuntu24.04",
    "storage_type":"zvol"
  }' http://127.0.0.1:8080/api/v1/vms

# VM 시작/중지/삭제
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8080/api/v1/vms/web-prod/start

curl -s -X POST ... http://127.0.0.1:8080/api/v1/vms/web-prod/stop
curl -s -X DELETE ... http://127.0.0.1:8080/api/v1/vms/web-prod

# VM 삭제 상태 확인 (비동기)
curl -s -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8080/api/v1/vms/web-prod/delete-status

컨테이너

# 목록
curl -s -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8080/api/v1/containers

# 생성
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"nginx-ct","image":"ubuntu:24.04"}' \
  http://127.0.0.1:8080/api/v1/containers

클러스터

Single Edge 공개판은 클러스터 상태, 클러스터 전체 VM, 라이브 마이그레이션 REST 절차를 운영 표면으로 제공하지 않는다.
관련 역사 기록은 docs/adr/와 Multi 범위 문서에서만 확인한다.

모니터링

# 호스트 메트릭
curl -s -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8080/api/v1/host/metrics

# 프로세스 목록
curl -s -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8080/api/v1/processes

# 알림 히스토리
curl -s -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8080/api/v1/alerts

# Prometheus 메트릭 (인증 불필요)
curl -s http://127.0.0.1:8080/api/v1/metrics

Health

# 심층 프로브 (인증 불필요)
curl -s http://127.0.0.1:8080/api/v1/health
# → {"status":"ok","subsystems":{
#     "libvirt":"ok","etcd":"ok","disk":"ok",
#     "audit_db":"ok","tls":"ok","capabilities":{...}
#   }}

---