# Bad: 동사 중심
GET /getUsers
POST /createUser
PUT /updateUser/123
DELETE /deleteUser/123

# Good: 명사 중심 (리소스)
GET /users           # 목록 조회
GET /users/123       # 단일 조회
POST /users          # 생성
PUT /users/123       # 전체 수정
PATCH /users/123     # 부분 수정
DELETE /users/123    # 삭제

# 관계 표현
GET /users/123/posts         # 사용자의 게시물
GET /posts/456/comments      # 게시물의 댓글

# 깊은 중첩 피하기 (3단계 이상)
# Bad
GET /users/123/posts/456/comments/789/likes

# Good: 직접 접근
GET /comments/789/likes

# 성공
200 OK           # 일반 성공
201 Created      # 리소스 생성 (POST 성공)
204 No Content   # 성공했지만 반환할 내용 없음 (DELETE)

# 클라이언트 에러
400 Bad Request      # 잘못된 요청
401 Unauthorized     # 인증 필요
403 Forbidden        # 권한 없음
404 Not Found        # 리소스 없음
409 Conflict         # 충돌 (중복 등)
422 Unprocessable    # 유효성 검증 실패

# 서버 에러
500 Internal Server Error  # 서버 오류
503 Service Unavailable    # 서비스 불가

// 단일 리소스
{
    "data": {
        "id": "123",
        "name": "John",
        "email": "john@example.com"
    }
}

// 목록 (페이지네이션)
{
    "data": [
        {"id": "1", "name": "John"},
        {"id": "2", "name": "Jane"}
    ],
    "pagination": {
        "page": 1,
        "perPage": 20,
        "total": 100,
        "totalPages": 5
    }
}

{
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Invalid input data",
        "details": [
            {
                "field": "email",
                "message": "Invalid email format"
            }
        ]
    }
}

GET /users?page=2&per_page=20

# 응답
{
    "data": [...],
    "pagination": {
        "page": 2,
        "per_page": 20,
        "total": 100
    }
}

GET /users?cursor=abc123&limit=20

# 응답
{
    "data": [...],
    "pagination": {
        "next_cursor": "def456",
        "has_more": true
    }
}

# 필터링
GET /users?status=active&role=admin

# 정렬
GET /users?sort=created_at&order=desc
GET /users?sort=-created_at  # 축약형

# 검색
GET /users?q=john

# 필드 선택
GET /users?fields=id,name,email

# 복합 예시
GET /users?status=active&sort=-created_at&fields=id,name&page=1

GET /v1/users
GET /v2/users

GET /users
Accept: application/vnd.api+json; version=2

# v1 유지하면서 v2 추가
/v1/users  # 기존 (deprecated)
/v2/users  # 신규

# Breaking Change 예시
# v1: { "name": "John" }
# v2: { "firstName": "John", "lastName": "Doe" }

# 응답 헤더
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640000000

# 429 응답 시
{
    "error": {
        "code": "RATE_LIMIT_EXCEEDED",
        "message": "Too many requests",
        "retry_after": 60
    }
}

Authorization: Bearer <token>

# 에러 응답
401 Unauthorized
{
    "error": {
        "code": "INVALID_TOKEN",
        "message": "Token expired or invalid"
    }
}

# 헤더
X-API-Key: <api_key>

# 또는 쿼리 파라미터 (비권장)
GET /users?api_key=<api_key>

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0

paths:
  /users:
    get:
      summary: Get all users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'