API 설계 가이드라인

RESTful API를 설계할 때 다음 원칙과 패턴을 따릅니다.

1. URL 설계 원칙

리소스 중심

# Good - 명사 사용
GET /users
GET /users/123
GET /users/123/orders

# Bad - 동사 사용
GET /getUsers
GET /getUserById/123
POST /createUser

복수형 사용

# Good
GET /users
GET /products
GET /orders

# Bad
GET /user
GET /product

계층 구조

# 리소스 간 관계 표현
GET /users/123/orders          # 특정 사용자의 주문 목록
GET /users/123/orders/456      # 특정 사용자의 특정 주문
POST /users/123/orders         # 특정 사용자에게 주문 생성

2. HTTP 메서드

사용 예시

GET    /users          # 목록 조회
GET    /users/123      # 단일 조회
POST   /users          # 생성
PUT    /users/123      # 전체 수정
PATCH  /users/123      # 부분 수정
DELETE /users/123      # 삭제

3. HTTP 상태 코드

성공 (2xx)

클라이언트 에러 (4xx)

서버 에러 (5xx)

4. 요청/응답 형식

요청 본문

POST /users
Content-Type: application/json

{
  "name": "홍길동",
  "email": "hong@example.com"
}

성공 응답

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "123",
  "name": "홍길동",
  "email": "hong@example.com",
  "createdAt": "2024-01-01T00:00:00Z"
}

에러 응답

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "유효성 검증에 실패했습니다",
    "details": [
      {
        "field": "email",
        "message": "올바른 이메일 형식이 아닙니다"
      }
    ]
  }
}

5. 페이지네이션

쿼리 파라미터

GET /users?page=1&limit=20
GET /users?offset=0&limit=20
GET /users?cursor=abc123&limit=20

응답 형식

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

6. 필터링 및 정렬

필터링

GET /users?status=active
GET /users?role=admin&status=active
GET /products?minPrice=1000&maxPrice=5000

정렬

GET /users?sort=createdAt:desc
GET /users?sort=name:asc,createdAt:desc

필드 선택

GET /users?fields=id,name,email

7. 버전 관리

URL 버전

GET /v1/users
GET /v2/users

헤더 버전

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

8. 보안 체크리스트

• HTTPS 사용
• 인증 (JWT, OAuth)
• 입력값 검증
• Rate Limiting
• CORS 설정
• 민감 정보 로깅 금지