콘텐츠로 이동

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

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

버전 표기

위치 값
URL 접두사 /api/v1/…
응답 헤더 X-API-Version: v1
봉투 meta.version "v1"

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

현재 상태

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

Changelog (v1)

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

2026-09-12 · JUMP 게임 썸네일

  • 기존 게임의 이미지 검사와 새 게임의 실제 화면 자동 캡처를 추가했습니다.
  • 작성자 전용 GET / POST /api/v1/contents/{id}/thumbnail-job으로 상태 확인·재생성을 지원합니다.
  • 직접 업로드한 이미지 보호, 원본 변경 시 재예약, 실패 재시도를 적용합니다. 썸네일 생성은 게임을 게시하지 않습니다.

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) 없이는 기존 클라이언트를 깨는 변경을 넣지 않는다.
    예: 필수 필드 추가·의미 변경, 성공 봉투 키 제거/이름 변경, 인증 방식 축소, 에러 코드 의미 뒤집기.
  2. 허용(비브레이킹): 선택 필드 추가, 새 엔드포인트, 새 에러 코드 추가, 문서화되지 않았던 동작을 명시, 한도 완화.
  3. 브레이킹이 필요하면:
  4. /api/v2를 병행 배포하고,
  5. X-API-Version / meta.version을 v2로 올리며,
  6. v1은 폐기 예고 기간을 둔 뒤 제거한다.
  7. DELETE 콘텐츠의 아카이브 시맨틱, Jump play의 경로=본문 ID 동일성, 업로드의 매직바이트 우선은 v1 계약의 일부로 취급한다. 이를 바꾸면 메이저 버전이 필요하다.
  8. Rate-limit 헤더의 더미 값을 실제 쿼터로 전환할 때는 헤더 의미 변경이므로 사전 공지 후, 가능하면 v2 또는 충분한 폐기 기간을 둔다.

폐기(Deprecation) 노트

항목 상태 안내
/api/v1/auth/signup v1에서 register와 동일 핸들러 새 연동은 register 권장. signup 제거 시 폐기 공지 예정
OAuth …/auth/oauth/{provider} 501 NOT_IMPLEMENTED provider secret 발급 전까지 구현 예정 없음. 호출해도 성공으로 취급하지 말 것
Rate-limit 헤더 수치 더미 프로덕션 쿼터로 오해하지 말 것 (errors.md)
레거시 Jump URL (/game/play/hg-… 등) 308 → 정규 /api/v1/jump/… 신규 클라이언트는 정규 경로만 사용
하드 삭제 기대 해당 없음 DELETE /contents/{id}는 아카이브. 복구/완전삭제 계약은 별도
v2 미착수 일정·스키마 확정 전 문서만 예약

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

관련 페이지

2026-09-12

  • 공개 API 문서를 MkDocs Material 기반의 docs.zuzunza.com으로 이전. 기존 /docs/api 링크 유지.
  • JUMP 초안과 게시 요청 분리, 공개 전 미리보기 권한 검사, 중복 게시 방지.
  • 최초 공개 기준 신규 게임 우선 정렬과 recent 최신순 별칭.
  • HTML5 ZWF2 패키지 재생, 이미지 AVIF·음원 업로드 및 저장소 장애 응답 반영.
  • 커뮤니티 사진 첨부·부분 수정·Unicode 해시태그 검색과 실제 지원 범위 문서화.