REST API 설계 베스트 프랙티스

URL 설계 원칙

명사 사용, 동사 금지

Good: GET /users
Bad:  GET /getUsers

Good: POST /orders
Bad:  POST /createOrder

복수형 사용

Good: /users, /posts, /comments
Bad:  /user, /post, /comment

계층 관계 표현

GET /users/123/posts         → 사용자 123의 게시글 목록
GET /users/123/posts/456     → 사용자 123의 게시글 456
POST /users/123/posts        → 사용자 123에 게시글 생성

HTTP 메서드

상태 코드

성공

클라이언트 에러

서버 에러

에러 응답 형식

일관된 에러 응답 구조:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "이메일 형식이 올바르지 않습니다.",
    "details": [
      {
        "field": "email",
        "message": "유효한 이메일 주소를 입력하세요."
      }
    ]
  }
}

페이지네이션

커서 기반 (추천)

GET /posts?cursor=abc123&limit=20

{
  "data": [...],
  "pagination": {
    "nextCursor": "def456",
    "hasMore": true
  }
}

오프셋 기반

GET /posts?page=2&limit=20

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 156,
    "totalPages": 8
  }
}

커서 기반이 더 좋은 이유: 대량 데이터에서 오프셋은 느려지고, 중간에 데이터가 추가/삭제되면 결과가 밀립니다.

필터링과 정렬

GET /posts?status=published&category=tech
GET /posts?sort=-createdAt       (내림차순)
GET /posts?sort=title            (오름차순)
GET /posts?fields=id,title,date  (필드 선택)

버전 관리

# URL 경로 (명확, 추천)
GET /api/v1/users
GET /api/v2/users

# 헤더
GET /api/users
Accept: application/vnd.myapp.v2+json

인증

Bearer Token (JWT)

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

API Key

X-API-Key: your-api-key

주의: API 키는 쿼리 파라미터가 아닌 헤더에 넣으세요. URL은 로그에 남습니다.

Rate Limiting

응답 헤더로 제한 정보 전달:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1617235200

실무 체크리스트

1. URL은 소문자 + 하이픈 (camelCase 금지)
2. 응답에 항상 적절한 상태 코드 사용
3. 에러 응답 형식 통일
4. 페이지네이션 구현 (기본 limit 설정)
5. CORS 설정
6. 요청/응답 로깅
7. API 문서화 (OpenAPI/Swagger)
8. Rate limiting 적용
9. 입력값 검증 (서버 사이드)
10. 민감 정보 응답에서 제외 (비밀번호 등)