REST API 레퍼런스

사바쨩 데몬이 노출하는 HTTP API. 인증 방식과 주요 엔드포인트 카탈로그.

REST API 레퍼런스

사바쨩 데몬(saba-core)은 127.0.0.1:57474에서 HTTP REST API를 제공합니다. GUI·CLI는 이 API만 호출하며, 서버쨩으로 들어온 디스코드 명령도 데몬 안에서 같은 기능을 거쳐 처리됩니다. 커스텀 클라이언트도 동일한 계약으로 만들 수 있습니다.

이 레퍼런스는 데몬의 라우트 정의(src/ipc/)에서 사용자·연동 개발자가 쓸 만한 라우트를 추려 요약한 것입니다. 내부용 라우트는 일부 생략했고, 필드 스키마는 바뀔 수 있으므로 최신 내용은 코드를 참조하세요.


1. 기본 사항

  • 베이스 URL: http://127.0.0.1:57474 (기본). SABA_IPC_PORT 환경변수 또는 config.json의 gui.ipcPort로 바꿀 수 있습니다(데몬 재시작 후 적용).
  • 바인딩 주소: 127.0.0.1로 고정되어 외부에서는 접근할 수 없습니다. Host 헤더가 루프백(127.0.0.1, localhost, ::1)이 아니면 403을 돌려줍니다.
  • 인증: /health를 제외한 모든 요청에 X-Saba-Token 헤더가 필요합니다. 토큰은 데몬이 시작할 때마다 새로 만들어 데이터 폴더의 .ipc_token 파일(Windows: %APPDATA%\saba-chan\.ipc_token)에 씁니다. 토큰이 없거나 틀리면 본문 없는 401입니다.
  • Content-Type: 요청 본문은 application/json입니다. 응답도 대부분 JSON입니다(익스텐션 GUI 번들·아이콘 등은 예외).
  • 에러 형식: 라우트에 따라 형식이 다릅니다. 대표적으로 {"error": "...", "error_code": "..."}, {"success": false, "error": ..., "error_code": ...}, {"ok": false, "error": ...}가 쓰입니다. 일부 라우트는 실패해도 HTTP 200에 ok:false를 돌려주므로 본문도 확인하세요.

2. 헬스체크 & 데몬

GET  /health                     # 토큰 불필요
GET  /api/version
GET  /api/diagnostics
GET  /api/events                 # 이벤트 스트림 (SSE)
POST /api/daemon/shutdown
  • /health: {"ok": true, "version": "x.y.z", "pid": 1234, "token": "valid" | "invalid" | "missing"}. token은 보낸 X-Saba-Token이 맞는지만 알려 주며 값은 드러내지 않습니다.
  • /api/version: {version, components: {...}} (코어·모듈·익스텐션 버전).
  • /api/events: Server-Sent Events. 주요 종류는 instance.exit(서버 종료·크래시 판정), backup.done, update.available, schedule.warn, provision.progress, action.run입니다. 끊겼다가 다시 붙을 때 Last-Event-ID 헤더나 ?since=<n>으로 놓친 이벤트를 받을 수 있습니다.
  • /api/daemon/shutdown: 데몬을 종료합니다.

3. 서버(인스턴스)

사바쨩은 서버 하나를 인스턴스로 관리합니다. 인스턴스는 UUID(id)로 가리킵니다.

3.1 목록과 생성·수정·삭제

GET    /api/servers                        # 서버 목록 + 실행 상태
GET    /api/instances                      # 인스턴스 목록
POST   /api/instances                      # 생성
POST   /api/instances/check                # 만들기 전 확인 (이름·폴더·포트 겹침, 아무것도 만들지 않음)
PUT    /api/instances/reorder              # body: { "order": [id, ...] }
GET    /api/instance/:id                   # 상세 (+ 약관 동의 상태 agreements)
PATCH  /api/instance/:id                   # 설정 변경 (키-값 객체)
DELETE /api/instance/:id                   # 삭제
POST   /api/instance/:id/rename            # body: { "name": "..." }
  • POST /api/instances 주요 필드: { "name", "module_name", "port"?, "preset"?, "module_settings"?, "version"?, "working_dir"?, "managed_start"?, "accept_agreements"?: [id] }. version을 비우면 최신 버전, working_dir은 새 서버를 설치할 빈 폴더(절대 경로), managed_start: false는 직접 관리 실행입니다. 모듈이 install_options로 정한 값 밖의 설치 값은 400 not_installable입니다. 성공 시 201 {success, id, ...}이며, 모듈이 설치를 정의하면 서버 파일 설치가 백그라운드로 시작됩니다(§3.5).
  • PATCH /api/instance/:id에는 포트, 모듈 설정 외에 다음 같은 데몬 설정도 넣을 수 있습니다.
    • auto_restart, restart_on_unknown_exit: 크래시·원인 모를 종료 뒤 자동 재시작 여부
    • extra_args: 추가 실행 인자 (문자열 또는 문자열 배열, null이면 비움)
    • memory_limit_mb: 메모리 상한(MiB, 256 이상. "4G"·"4096M" 형식도 허용, null·0은 제한 없음). Windows에서만 적용됩니다.
  • 이름 변경은 서버가 꺼져 있어야 하며, 이미 쓰는 이름이면 409 name_taken입니다.

3.2 시작 / 정지 / 재시작

POST /api/instance/:id/start
POST /api/instance/:id/stop                # 선택 body: { "force": true }
POST /api/instance/:id/restart             # 선택 body: { "force": true }
GET  /api/instance/:id/events              # 최근 종료 이력
GET  /api/instance/:id/status              # 상태 조회
  • 시작 전에 데몬이 약관 동의와 모듈 점검을 확인합니다. 동의하지 않은 약관이 있으면 409 agreement_required(agreements 포함), 점검에서 치명적 문제가 나오면 409 preflight_failed입니다.
  • 정지는 게임의 정상 종료 명령을 보내고 모듈이 정한 시간(기본 30초)만큼 기다린 뒤, 그래도 살아 있으면 강제 종료합니다. force: true면 바로 강제 종료합니다.
  • events는 {events: [...]}로, 종료 판정(user_stop, in_game_stop, crash, unknown_exit)과 근거, 자동 재시작 예정 등을 담습니다.

3.3 콘솔과 명령

GET  /api/instance/:id/console?since=<id>&count=<n>
POST /api/instance/:id/stdin               # body: { "command": "say hello" }
POST /api/instance/:id/command             # body: { "command": "<이름>", "args"?: {...} }
GET  /api/instance/:id/commands            # 이 서버에서 쓸 수 있는 명령 목록
POST /api/instance/:id/rest                # REST 전용 게임(예: 팰월드)
POST /api/instance/:id/rcon                # 호환용 이름. 아래 명령 경로(stdin → REST → RCON)를 따름
  • 콘솔 폴링: 응답은 {success, lines: [{id, timestamp, source, content, level}], running, ...}입니다. since를 주면 그 id 이상의 줄을 돌려주므로, 다음 요청에는 마지막으로 받은 id + 1을 보내세요. since 없이 부르면 최근 count줄(기본 100)을 줍니다. 데몬은 서버마다 최근 1만 줄을 메모리에 둡니다.
  • 명령 경로 순서는 stdin → REST → RCON입니다. 명령은 먼저 서버 콘솔(stdin)로 가고, 팰월드처럼 REST만 지원하는 게임은 REST로 갑니다. RCON은 모듈이 supported = ["rcon"]으로 선언한 게임(콘솔도 REST API도 없는 게임)에만 쓰이며, 이때 데몬이 인스턴스마다 포트와 무작위 비밀번호를 정하고 루프백(127.0.0.1)으로만 연결합니다. 그 밖의 경우 /rcon은 예전 클라이언트를 위해 이름만 남은 경로로, stdin으로 보냅니다. 명령 경로가 없는 서버면 409 no_command_path입니다.
  • /stdin은 모듈이 stdin을 지원하지 않으면 409 stdin_not_supported입니다.
  • /command는 모듈이 정의한 명령을 실행하고, 서버가 꺼져 있으면 409 server_not_running입니다.

3.4 설정·약관·점검

POST /api/instance/:id/launch-preview      # body: { "settings"?: {...}, "extra_args"?: "..." }
POST /api/instance/:id/agreements          # body: { "accept": ["eula"] }
GET  /api/instance/:id/properties          # 게임 설정 파일 읽기
PUT  /api/instance/:id/properties          # body: { "settings": {...} }
POST /api/instance/:id/validate            # 서버 점검
POST /api/instance/:id/diagnose            # 로그 진단
  • launch-preview는 서버를 켜지 않고 실행 명령줄을 계산합니다. 응답 예: {success: true, has_launch_args, command_line, program, args, extra_args, errors: [...]}. 비밀번호 값은 ***로 가립니다. 모듈이 실행 인자를 선언하지 않았으면 has_launch_args: false입니다.
  • agreements는 모듈이 선언한 약관(예: 마인크래프트 eula)에 동의를 기록합니다. 로컬에서만 할 수 있고, 원격(디스코드 등)에서 오면 403 agreement_local_only입니다. 선언되지 않은 id는 400 invalid_format입니다.

3.5 설치 진행률과 게임 서버 업데이트

GET    /api/provision-progress/:name       # :name = 인스턴스 이름
DELETE /api/provision-progress/:name       # 실패한 진행 상태 닫기
GET    /api/instance/:id/check-update
POST   /api/instance/:id/apply-update

provision-progress 응답 예:

{
  "active": true,
  "step": 2,
  "total": 5,
  "label": "...",
  "message": "...",
  "percent": 40,
  "done": false,
  "error": null
}

진행 중인 작업이 없으면 {"active": false}입니다. 성공한 진행 상태는 5초 뒤 자동으로 정리되고, 실패한 상태는 DELETE로 닫을 때까지 남습니다(새로 만들던 서버였다면 이때 롤백됩니다). 진행률은 /api/events의 provision.progress로도 받을 수 있습니다.

apply-update는 서버가 켜져 있으면 409 server_running입니다. 업데이트 전에 백업을 먼저 만듭니다(백업을 지원하는 모듈).

3.6 백업과 예약 작업

GET    /api/instance/:id/backups                     # { success, backups: [{ name, kind, created, size }] }
POST   /api/instance/:id/backups                     # 지금 백업
DELETE /api/instance/:id/backups/:name
POST   /api/instance/:id/backups/:name/restore       # 서버가 꺼져 있어야 함
GET    /api/instance/:id/schedule
PUT    /api/instance/:id/schedule                    # body: { "schedule": [...], "backup_keep"?: 10 }
  • 백업 kind: manual, scheduled, pre-update, pre-restore. 모듈이 백업을 지원하지 않으면 400 backup_unsupported, 아직 백업할 파일이 없으면 400 nothing_to_back_up입니다.
  • 복원은 서버가 켜져 있으면 409 server_running이며, 복원 전에 지금 상태를 pre-restore로 백업합니다.
  • 예약 작업 한 건의 형식:
{ "action": "restart", "at": "05:00", "warn_minutes": [10, 5, 1], "enabled": true }

action은 backup | restart | announce | update이고, every_minutes(N분마다)와 at(매일 HH:MM) 중 하나만 씁니다. announce에는 message가 필요하고, warn_minutes는 restart·update에만 쓸 수 있습니다. 규칙에 맞지 않으면 400 validation_failed(details 포함)입니다.


4. 모듈

GET    /api/modules                        # 설치된 모듈 목록
POST   /api/modules/refresh                # 모듈 폴더 다시 읽기
GET    /api/module/:name                   # 모듈 메타데이터
GET    /api/module/:name/versions          # 설치 가능한 게임 서버 버전
GET    /api/module/:name/locales
GET    /api/modules/manifest               # 설치할 수 있는 모듈 카탈로그
POST   /api/modules/manifest/:id/install   # 카탈로그에서 모듈 설치
DELETE /api/modules/:id                    # 모듈 제거

모듈 카탈로그는 서명된 릴리스 목록에서 오며, 받은 파일은 해시를 확인한 뒤 설치합니다.


5. 익스텐션

GET    /api/extensions                     # 설치/활성 상태 포함 목록
POST   /api/extensions/rescan
GET    /api/extensions/manifest            # 설치할 수 있는 익스텐션 카탈로그
GET    /api/extensions/updates
POST   /api/extensions/:id/install
DELETE /api/extensions/:id
POST   /api/extensions/:id/enable          # daemon.startup 훅 비동기 실행
POST   /api/extensions/:id/disable

GET    /api/extensions/:id/config
PUT    /api/extensions/:id/config

GET    /api/extensions/:id/gui             # GUI 번들 (UMD JavaScript)
GET    /api/extensions/:id/gui/styles      # CSS
GET    /api/extensions/:id/i18n/:locale    # ko / en / ja / ...

익스텐션 라우트의 에러는 {success: false, error, error_code, ...} 형식입니다.


6. 설정

GET  /api/config/gui
PUT  /api/config/gui                       # 부분 JSON (얕은 머지)
GET  /api/config/bot
PUT  /api/config/bot                       # 접두사·별명 등 봇 설정 (부분 JSON)
GET  /api/system/metrics                   # CPU·메모리·디스크·서버별 사용량

모든 사용자 설정은 데이터 폴더의 config.json 한 파일에 네임스페이스별로 저장됩니다. 봇 설정은 데몬이 서버쨩에 동기화합니다. 디스코드 봇 자체는 서버쨩에서 돌기 때문에 데몬에 봇 프로세스를 시작/정지하는 API는 없습니다.


7. 업데이트

GET  /api/updates/status                   # 현재 상태와 구성요소별 버전
POST /api/updates/check                    # 지금 업데이트 확인
POST /api/updates/download                 # 선택 body: { "components": [...] }
GET  /api/updates/download/progress
POST /api/updates/apply                    # 선택 body: { "components": [...] }
POST /api/updates/launch-updater           # 설치 프로그램으로 적용 (데몬 종료 동반)
GET  /api/updates/config
PUT  /api/updates/config

업데이트 정보는 서명된 릴리스 목록에서 옵니다. 실행 중인 파일을 바꿔야 하는 구성요소는 apply 응답에 별도 적용이 필요하다고 표시되며, launch-updater를 부르면 설치 프로그램(saba-chan-installer --apply)이 데몬을 종료·교체하고 바뀐 것만 다시 띄웁니다. 이 라우트들의 응답은 {ok: ...} 형식입니다.


8. 서버쨩 페어링

GUI ↔ 서버쨩 페어링 흐름용입니다. 자세한 흐름은 디스코드 봇 문서를 참고하세요.

POST   /api/relay/pair/initiate            # 페어링 코드 발급 (서버쨩으로 전달)
GET    /api/relay/pair/:code/status        # 페어링 완료 여부 폴링
GET    /api/relay/agent                    # 서버쨩 에이전트 상태
POST   /api/relay/agent/start
POST   /api/relay/agent/stop
DELETE /api/config/node-token              # 이 PC의 노드 토큰 삭제 (에이전트 정지)

페어링이 완료되면(status: "claimed") 데몬이 노드 토큰을 자동으로 저장하고 서버쨩 에이전트를 새 토큰으로 다시 연결합니다. 서버쨩 인증은 데몬이 처리하므로 클라이언트가 직접 다룰 필요는 없습니다.


9. 인증 예제 (curl)

TOKEN=$(cat "$APPDATA/saba-chan/.ipc_token")

curl -H "X-Saba-Token: $TOKEN" \
     http://127.0.0.1:57474/api/servers

curl -X POST \
     -H "X-Saba-Token: $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"command":"list"}' \
     http://127.0.0.1:57474/api/instance/<instance-id>/stdin

<instance-id>는 GET /api/servers 또는 GET /api/instances 응답의 id입니다.


10. 버전 호환성

  • 이 API는 프라이빗 IPC로 분류됩니다. 공용 계약이 아니므로 마이너 버전에서도 경로/스키마가 바뀔 수 있습니다.
  • 커스텀 클라이언트를 배포한다면 데몬 버전을 확인(GET /health의 version)하고 보수적으로 다루세요.

문제가 있다면 문제 해결로.