ZUKU API — 변경 이력 · 버전 정책

> 브랜드: ZUKU API

> 구현 기준: backend/rs/src/router.rs에 실제로 라우팅된 기능만 기록한다.

---

버전 표기

세 위치가 같은 API 세대를 가리킨다. 클라이언트는 URL의 v1을 소스 오브 트루스로 두고, 헤더/meta는 관측·로깅용으로 쓴다.

현재 상태

• v1: 활성 (스테이징/프로덕션 계약)
• v2: 계획만 있음 — 경로·봉투·브레이킹 변경이 필요할 때 도입. 현시점 라우터에 /api/v2 없음

---

Changelog (v1)

구현 반영 요약. 날짜는 문서 정리 기준이며, 세부 커밋 해시는 저장소 이력을 따른다.

Social · 팔로우

• follows 테이블 + POST /creators/{handle}/follow 토글
• 공개 프로필 follower_count / following_count / is_following 실측
• 피드 sort=following — 팔로우한 작성자 작품만

Auth · Captcha · 문서

• 위키: docs/api-wiki/ + 사이트 /docs/api (Captcha · Examples 상세 페이지 포함)

Auth · 세션

• POST /api/v1/auth/register · signup — 가입(캡차 게이트, 레거시 계정 충돌 차단)
• POST /api/v1/auth/login · logout · refresh
• GET / PATCH /api/v1/auth/me
• GET /api/v1/auth/sessions · DELETE …/sessions/{id} — 활성 세션 목록·폐기
• POST /api/v1/auth/oauth/{provider} — 501 NOT_IMPLEMENTED (스코프 아웃)

Captcha

• POST /api/v1/captcha/challenge · verify — 자체 호스팅 PoW
• 시크릿 미설정 시 CAPTCHA_NOT_CONFIGURED로 fail-closed

Feeds · Contents

• GET /api/v1/feeds 및 /feeds/hype|swipe|jump
• GET /api/v1/contents/{id}
• GET /api/v1/contents/{id}/conversion
• GET /api/v1/contents/{id}/recommendations — limit 1–50(기본 8), offset; LIMIT+1 has_more, 비로그인 짧은 캐시
• GET /api/v1/jump/games/{id}?include=related,popular — 점프 상세 선반을 같은 봉투에 첨부
• POST /api/v1/contents — Bearer 또는 X-API-Key
• PATCH / DELETE /api/v1/contents/{id} — Bearer만; DELETE는 아카이브
• POST …/like · POST …/bookmark
• 댓글: GET/POST …/comments, PATCH/DELETE /api/v1/comments/{id}

Uploads · Jump stream

• POST /api/v1/uploads — multipart, 매직바이트 MIME, 크기 한도
• GET /uploads/{path} — API 접두사 없는 정적 서빙
• GET /api/v1/jump/games · GET …/games/{id}
• POST …/play · …/stream(IR) · …/swf — POST는 인증 필수

Developer keys

• POST / GET /api/v1/developer/keys
• DELETE /api/v1/developer/keys/{id}
• 발급 키로 콘텐츠 생성(X-API-Key) 가능

Community posts

• GET /api/v1/feed — 타임라인
• POST /api/v1/posts · GET …/posts/{id} · GET …/thread
• POST …/replies · POST/DELETE …/like · DELETE …/posts/{id}

DM

• GET/POST /api/v1/dm/conversations
• GET/POST …/conversations/{id}/messages
• POST …/conversations/{id}/read
• 1:1 평문 저장 (E2E·그룹챗은 스코프 밖)

Notifications

• GET /api/v1/notifications
• GET …/unread-count
• POST …/read-all · POST …/{id}/read

기타 (라우터에 존재)

• GET /api/health
• GET /api/wasm/contract
• 관리자 사용자 조회/패치, 레거시 Jump 경로 308 리다이렉트
• moderation / analytics 모듈 위임 경로 (각 모듈 게이트)

---

브레이킹 체인지 정책 (요약)

1. URL 메이저(v1 → v2) 없이는 기존 클라이언트를 깨는 변경을 넣지 않는다.

예: 필수 필드 추가·의미 변경, 성공 봉투 키 제거/이름 변경, 인증 방식 축소, 에러 코드 의미 뒤집기.

1. 허용(비브레이킹): 선택 필드 추가, 새 엔드포인트, 새 에러 코드 추가, 문서화되지 않았던 동작을 명시, 한도 완화.
2. 브레이킹이 필요하면:

- /api/v2를 병행 배포하고,

- X-API-Version / meta.version을 v2로 올리며,

- v1은 폐기 예고 기간을 둔 뒤 제거한다.

1. DELETE 콘텐츠의 아카이브 시맨틱, Jump play의 경로=본문 ID 동일성, 업로드의 매직바이트 우선은 v1 계약의 일부로 취급한다. 이를 바꾸면 메이저 버전이 필요하다.
2. Rate-limit 헤더의 더미 값을 실제 쿼터로 전환할 때는 헤더 의미 변경이므로 사전 공지 후, 가능하면 v2 또는 충분한 폐기 기간을 둔다.

---

폐기(Deprecation) 노트

폐기 예정 API는 최소 한 메이저 주기 동안 병행하고, 응답 또는 문서에 대체 경로를 명시한다.

---

관련 페이지

• contents.md
• media.md
• errors.md