App Backend REST API 개요

이 문서는 sohri-app-backend 기준 커밋 00fd523의 컨트롤러, 요청 DTO, 검증기와 응답 VO를 기준으로 작성한 호출자용 명세입니다. 모든 업무 API의 기본 prefix는 /v1이며 App Backend는 WebSocket 서버가 아닙니다.

문서 구성

• 인증·회원·개인 설정
• 워크스페이스·API key·client-secret·사용자 그룹
• 시나리오·템플릿·Graph Builder 검증
• 대화·메시지·분석·음성
• 공통 스키마

설계 배경과 운영상 주의는 로그인과 토큰 인증, 워크스페이스와 테넌시, API key와 client-secret, 공유 데이터 계약, 보안과 현재 격차를 함께 참고하십시오. 전체 경로의 빠른 색인은 REST API 참조에 있습니다.

기본 호출 규칙

Authorization: Bearer <credential>
Content-Type: application/json
X-Workspace-Id: 01900000-0000-7000-8000-000000000001

Authorization 값으로 사용할 수 있는 credential은 서로 대체되지 않습니다.

종류	용도	서명·형태	이 API에서의 사용
access JWT	로그인 회원의 REST 요청	HMAC JWT, type=access	회원·워크스페이스·시나리오 쓰기/읽기
refresh JWT	access/refresh 재발급	HMAC JWT, type=refresh	POST /v1/auth/refresh 본문에만 전달
워크스페이스 API key	서버 간 제한적 읽기	랜덤 장기 credential	허용된 GET에 SCOPE_WORKSPACE_READ로 사용
Ed25519 client-secret	Socket Backend 실시간 세션	EdDSA JWT	App Backend에서 발급만 하며 REST 인증에는 사용하지 않음

즉, API key는 access JWT가 아니고, client-secret도 API key나 access JWT가 아닙니다. client-secret을 Authorization에 넣어 App Backend를 호출하는 계약은 없습니다.

인증과 테넌트 선택

• 공개: 인증 회원가입·로그인·재발급, 기본/더미 시나리오, /healthz.
• access JWT: Authorization: Bearer <access-jwt>.
• API key: 허용된 읽기 경로에서 Authorization: Bearer <workspace-api-key>.
• JWT 기반 테넌트 요청: X-Workspace-Id가 필요합니다. UUID 형식과 ACTIVE 멤버십을 먼저 확인하며, 형식 오류는 400, 비멤버는 403입니다.
• API key 요청: 키의 귀속 워크스페이스가 자동 선택됩니다. 헤더를 함께 보낸다면 그 값이 키의 워크스페이스와 일치해야 합니다.

워크스페이스 생성·내 소속 목록, 전역 템플릿 목록, 음색 프리셋, 회원 개인 설정은 워크스페이스 비종속이므로 X-Workspace-Id가 필요 없습니다.

대화 조회의 구현상 예외

대화 목록·상세·세션 상세는 API key일 때 귀속 워크스페이스로 격리됩니다. JWT 요청은 기준 커밋에서 헤더가 없으면 테넌트 컨텍스트 없이 진행될 수 있으므로 호출자는 항상 X-Workspace-Id를 보내야 합니다. 음성 프록시와 대화 통계는 JWT 헤더를 실제로 강제합니다. 자세한 내용은 워크스페이스와 테넌시 및 대화·분석 API를 참고하십시오.

공통 응답

단건 응답:

{
  "status": 200,
  "message": "success",
  "data": {}
}

페이지 응답:

{
  "status": 200,
  "message": "success",
  "page": {
    "page": 1,
    "size": 20,
    "totalItems": 42,
    "totalPages": 3,
    "hasNext": true,
    "hasPrevious": false,
    "first": true,
    "last": false
  },
  "count": 20,
  "list": []
}

페이지 query는 page 기본 1, size 기본 20입니다. page < 1은 1로, size는 1..10,000 범위로 보정됩니다. count는 현재 페이지의 항목 수이고 totalItems는 전체 검색 결과 수입니다.

오류 응답:

{
  "status": 400,
  "message": "요청 값이 올바르지 않습니다."
}

일부 오류는 data.code와 관련 식별값을 추가합니다. 전체 envelope와 필드 계약은 공통 스키마와 공유 데이터 계약을 참고하십시오.

HTTP status를 우선하십시오

생성 성공이 실제 HTTP 201이어도 공통 성공 객체의 status 필드는 구현상 200입니다. 클라이언트는 본문의 status보다 HTTP 응답 status line을 우선해야 합니다.

대표 상태 코드

• 200 OK: 조회, 갱신, 이력 append, 멱등 삭제/폐기 성공
• 201 Created: 회원가입, 신규 리소스 또는 client-secret 발급
• 400 Bad Request: 필드 검증, UUID/날짜/enum 형식, 필수 테넌트 누락
• 401 Unauthorized: credential 누락·불일치·만료, 잘못된 refresh token
• 403 Forbidden: 역할, OWNER 또는 워크스페이스 멤버십 부족
• 404 Not Found: 리소스 부재 또는 다른 테넌트의 리소스를 숨긴 결과
• 409 Conflict: 활성 유일키 중복, 불변 provenance 충돌, 비활성 설정값
• 503 Service Unavailable: Graph Builder/DM 또는 음성 저장소 장애

상태 확인

GET /healthz

• 인증·테넌트: 공개
• 요청 본문: 없음
• 응답: 200 text/plain

ok

DB나 외부 의존성을 확인하지 않는 최소 ping이며 버전·빌드·프로파일도 노출하지 않습니다. Actuator는 별도의 운영 노출 정책을 따르므로 업무 클라이언트가 의존해서는 안 됩니다.