Skip to content

API_SPEC.md

Latest commit

 

History

History
306 lines (217 loc) · 8.94 KB

API_SPEC.md

File metadata and controls

306 lines (217 loc) · 8.94 KB
Raw

API 명세 (v1)

1. 개요

  • 서비스명: philosopher-server
  • 프레임워크: FastAPI
  • API 버전 Prefix: /api/v1
  • 문서 기준일: 2026-04-15

2. 공통 규약

  • 콘텐츠 타입: application/json
  • 인증: /api/v1 하위 대부분 엔드포인트는 Authorization: Bearer <Supabase Access Token> 필요
  • JWT 검증: Supabase JWKS 기반 서명 검증, RS256/ES256 알고리즘 허용
  • 공통 응답 포맷: 현재는 엔드포인트별 단순 JSON 응답 사용
  • 사용자 격리: 프로젝트/대화/메시지는 토큰의 sub(user id) 기준으로 분리 저장

3. 엔드포인트 명세

3.1 GET /health

성공 응답:

{
  "status": "ok"
}

3.2 GET /api/v1/health

성공 응답:

{
  "status": "ok"
}

3.3 GET /api/v1/me

현재 로그인한 사용자 정보를 반환합니다.

성공 응답:

{
  "id": "b6450d8d-1748-4364-8a1a-6e6ce6d8ce64",
  "email": "user@example.com",
  "role": "authenticated"
}

3.4 POST /api/v1/chat/projects

사용자 프로젝트를 생성합니다.

요청:

{
  "name": "윤리학 프로젝트",
  "description": "도덕 철학 대화",
  "instruction": "항상 핵심 요약 3줄을 마지막에 추가"
}

주요 오류 응답:

  • 409: 동일 사용자에게 같은 이름의 프로젝트가 이미 존재함 (Project name already exists)

3.5 GET /api/v1/chat/projects

현재 사용자 프로젝트 목록을 반환합니다.

  • 기본 프로젝트(is_default=true)는 내부 개념으로만 사용되며 목록에 노출되지 않습니다.
  • 목록 정렬: updated_at 내림차순, created_at 내림차순

3.6 PATCH /api/v1/chat/projects/{project_id}/settings

프로젝트 설정을 수정합니다.

요청(필드 중 최소 1개 필요):

{
  "name": "윤리학 프로젝트 v2",
  "instruction": "답변 전에 반례를 먼저 검토해"
}

주요 오류 응답:

  • 409: 동일 사용자에게 같은 이름의 프로젝트가 이미 존재함 (Project name already exists)

3.7 POST /api/v1/chat/conversations

일반 채팅용 대화를 생성합니다.

  • 서버는 사용자별 기본 프로젝트(숨김)를 내부적으로 생성/재사용하며, 사용자는 기본 프로젝트를 직접 볼 필요가 없습니다.
  • title을 생략하면 null로 저장되며, 첫 메시지 전송 시 사용자 첫 메시지 기반으로 자동 제목이 설정됩니다.

요청:

{
  "philosopher": "plato",
  "title": "일반 채팅"
}
  • philosopher 허용값: socrates, nietzsche, hannah_arendt, plato, aristotle, rene_descartes, immanuel_kant, confucius, simone_de_beauvoir

3.8 POST /api/v1/chat/projects/{project_id}/conversations

특정 프로젝트에 철학자 대화를 생성합니다.

요청:

{
  "philosopher": "plato",
  "title": "정의란 무엇인가"
}
  • philosopher 허용값: socrates, nietzsche, hannah_arendt, plato, aristotle, rene_descartes, immanuel_kant, confucius, simone_de_beauvoir
  • title을 생략하면 null로 저장되며, 첫 메시지 전송 시 사용자 첫 메시지 기반으로 자동 제목이 설정됩니다.

3.9 GET /api/v1/chat/projects/{project_id}/conversations

프로젝트 단위 대화 목록을 조회합니다.

3.10 PATCH /api/v1/chat/conversations/{conversation_id}/project

대화의 소속 프로젝트를 변경합니다(프로젝트 이동).

  • project_id가 null이면 사용자 기본 프로젝트(숨김)로 이동합니다.

요청:

{
  "project_id": "target-project-id"
}

3.11 POST /api/v1/chat/conversations/{conversation_id}/messages

사용자 메시지를 저장하고, 선택된 철학자 페르소나로 AI 응답을 생성해 함께 저장합니다.

  • 대화 제목이 비어 있는 경우, 첫 메시지 전송 시 해당 메시지 내용 기반으로 제목이 자동 설정됩니다.
  • 자동 제목은 공백 정규화 후 최대 80자로 저장됩니다.

요청:

{
  "content": "정의는 배울 수 있는가?"
}

성공 응답:

{
  "user_message": {
    "id": "...",
    "role": "user",
    "content": "정의는 배울 수 있는가?",
    "created_at": "2026-04-13T14:21:00.000000Z"
  },
  "assistant_message": {
    "id": "...",
    "role": "assistant",
    "content": "...",
    "created_at": "2026-04-13T14:21:01.000000Z"
  }
}

주요 오류 응답:

  • 404: 다른 사용자 소유 대화 또는 존재하지 않는 대화 (Conversation not found)
  • 503: OPENAI_API_KEY 누락 (OPENAI_API_KEY is not configured)
  • 502: OpenAI 호출 실패/빈 응답

3.12 GET /api/v1/chat/conversations/{conversation_id}/messages

대화 메시지 히스토리를 시간순으로 조회합니다.

3.13 DELETE /api/v1/chat/conversations/{conversation_id}

대화 1개를 삭제합니다.

  • 본인 소유 대화만 삭제할 수 있습니다.
  • 삭제 성공 시 204 No Content를 반환합니다.
  • 대화에 속한 메시지는 함께 삭제됩니다.

주요 오류 응답:

  • 404: 다른 사용자 소유 대화 또는 존재하지 않는 대화 (Conversation not found)

3.14 DELETE /api/v1/chat/projects/{project_id}

프로젝트 1개를 삭제합니다.

  • 본인 소유 일반 프로젝트만 삭제할 수 있습니다.
  • 기본 프로젝트(is_default=true)는 삭제 대상이 아닙니다.
  • 삭제 성공 시 204 No Content를 반환합니다.
  • 프로젝트에 속한 대화와 메시지는 모두 함께 삭제됩니다.

주요 오류 응답:

  • 404: 다른 사용자 소유 프로젝트 또는 존재하지 않는 프로젝트 (Project not found)

3.15 POST /api/v1/tts

철학자 고정 voice 매핑 기반으로 서버에서 Neural TTS를 생성하고, audio/mpeg 바이너리를 직접 반환합니다.

요청:

{
  "philosopher_id": "plato",
  "text": "정의는 가르칠 수 있는가?"
}
  • philosopher_id 허용값: socrates, nietzsche, hannah_arendt, plato, aristotle, rene_descartes, immanuel_kant, confucius, simone_de_beauvoir

성공 응답:

  • 200 OK
  • Content-Type: audio/mpeg
  • 응답 본문: MP3 바이너리

요청 정책:

  • 텍스트 길이 제한: 최대 2,000자
  • 텍스트 전처리: 마크다운/특수기호 최소 정리
  • 내부 분할 처리: 긴 텍스트는 provider 요청 단위로 분할
  • timeout/retry: provider 호출당 8초 timeout, 실패 시 1회 retry
  • rate limit: 사용자 기준 분당 요청 제한 적용

오류 응답(JSON):

  • 400 TTS_INVALID_REQUEST: 잘못된 요청 바디
  • 400 TTS_INVALID_TEXT: 전처리 후 텍스트가 비어 있음
  • 400 TTS_TEXT_TOO_LONG: 최대 길이 초과
  • 401 TTS_UNAUTHORIZED: 사용자 클레임 불량
  • 429 TTS_RATE_LIMITED: 요청 과다
  • 502 TTS_PROVIDER_ERROR|TTS_PROVIDER_UNAVAILABLE: provider 오류
  • 503 TTS_NOT_CONFIGURED: OPENAI_API_KEY 미설정
  • 504 TTS_PROVIDER_TIMEOUT: provider timeout

4. 환경 변수

  • DATABASE_URL: 미설정 시 sqlite:///./.local/philosopher.db 사용
  • OPENAI_API_KEY: 철학자 AI 응답 생성에 필요
  • TTS_OPENAI_MODEL: TTS 모델 (기본 gpt-4o-mini-tts)
  • TTS_TIMEOUT_SECONDS: provider timeout 초 (기본 8)
  • TTS_RETRY_COUNT: provider 재시도 횟수 (기본 1)
  • TTS_MAX_CHARS: 요청 텍스트 최대 길이 (기본 2000)
  • TTS_CHUNK_CHARS: provider 분할 호출 기준 길이 (기본 500)
  • TTS_RATE_LIMIT_PER_MINUTE: 사용자별 분당 요청 제한 (기본 20)
  • 모델은 서버에서 gpt-4o-mini로 고정

5. AI 연동 정책

  • OpenAI API: POST /v1/responses
  • 모델: gpt-4o-mini (환경변수로 변경 불가)
  • 철학자 시스템 프롬프트는 서버에서 고정 관리:
    • socrates
    • nietzsche
    • hannah_arendt
    • plato
    • aristotle
    • rene_descartes
    • immanuel_kant
    • confucius
    • simone_de_beauvoir
  • 프로젝트에 instruction이 설정된 경우, 철학자 시스템 프롬프트 뒤에 결합되어 대화 생성에 반영됩니다.

6. 자동 생성 OpenAPI 문서

  • Swagger UI: GET /docs
  • ReDoc: GET /redoc
  • OpenAPI JSON: GET /openapi.json

7. 버전 정책

  • 현재 버전: v1
  • 하위 호환성을 깨는 변경은 신규 버전 Prefix(예: /api/v2)로 분리합니다.

8. 변경 이력

  • 2026-04-13: 헬스체크/인증 API 추가
  • 2026-04-13: 프로젝트/철학자 대화/메시지 저장 API 추가
  • 2026-04-13: OpenAI 모델 gpt-4o-mini 고정 정책 반영
  • 2026-04-14: 프로젝트 이동/설정 수정 API 추가
  • 2026-04-14: 일반 채팅용 기본 프로젝트(숨김) 개념 도입
  • 2026-04-14: 프로젝트 지침(instruction) AI 반영
  • 2026-04-14: 프로젝트 삭제/대화 삭제 API 추가
  • 2026-04-14: 사용자별 프로젝트 이름 중복 방지(409) 추가
  • 2026-04-14: 제목 없는 대화의 첫 메시지 전송 시 자동 제목 설정 추가
  • 2026-04-15: 기존 3인(socrates, nietzsche, hannah_arendt) 유지 + 신규 6인 추가로 총 9인 지원