API 설계: RESTful 엔드포인트 전체 설계

1. Resource = 명사 (URL)         /generations  ✓  /createGen ✗
2. Method   = 동사 (HTTP)         POST /generations
3. Status   = 결과 표준           200/201/400/401/404/429/500
4. Stateless = 매 요청 독립        토큰만으로 인증
5. Cacheable = HTTP 캐시 활용
6. Layered  = 클라이언트는 서버 내부 모름

[Auth]
POST   /api/auth/login       — 이메일/비밀번호 로그인
POST   /api/auth/signup      — 회원가입
POST   /api/auth/logout      — 로그아웃
GET    /api/auth/me          — 현재 사용자

[Generations] (메인)
POST   /api/generations              — AI 생성
GET    /api/generations              — 목록 (검색·필터)
GET    /api/generations/:id          — 상세
PATCH  /api/generations/:id          — 수정
DELETE /api/generations/:id          — 삭제

[Templates]
GET    /api/templates                — 템플릿 목록
GET    /api/templates/:id            — 템플릿 상세

[Subscriptions]
GET    /api/subscriptions/me         — 현재 구독
POST   /api/stripe/checkout          — Stripe Checkout 세션
POST   /api/stripe/portal            — Customer Portal
POST   /api/stripe/webhook           — Stripe Webhook

[Usage]
GET    /api/usage                    — 사용량

[Files]
POST   /api/files/upload             — 파일 업로드 (Storage)
DELETE /api/files/:id                — 삭제

[Notifications]
GET    /api/notifications            — 목록
PATCH  /api/notifications/read-all   — 모두 읽음

[2xx]
200 OK              GET·PATCH·DELETE 성공
201 Created         POST 성공 (Location 헤더)
204 No Content      응답 본문 없음

[4xx — 클라이언트 잘못]
400 Bad Request     입력값 오류
401 Unauthorized    인증 누락
403 Forbidden       권한 부족
404 Not Found
409 Conflict        중복
422 Unprocessable   검증 실패
429 Too Many        Rate limit

[5xx — 서버 잘못]
500 Internal Error
502 Bad Gateway     업스트림 에러
503 Service Unavailable
504 Gateway Timeout

// 성공
{
  "data": { "id": "...", "result": "..." },
  "meta": { "remaining_quota": 4 }
}

// 에러
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "분당 10회 초과",
    "retry_after": 30
  }
}

// 목록
{
  "data": [...],
  "meta": { "cursor": "...", "has_more": true }
}

1. URL: /api/v1/generations  ← 가장 흔함
2. 헤더: Accept: application/vnd.mysaas.v1+json
3. 쿼리: /api/generations?v=1

추천: URL 버저닝 (간단·명확)
파괴적 변경 시에만 v2 (대부분 v1 유지)

# openapi.yaml
openapi: 3.0.0
info:
  title: My SaaS API
  version: 1.0.0
paths:
  /api/generations:
    post:
      summary: AI 생성
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                prompt: { type: string, maxLength: 500 }
              required: [prompt]
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Generation' }

# Swagger UI 자동 생성
pnpm add @scalar/api-reference-react
# /api/docs 페이지에서 인터랙티브 API 문서