REST API 설계

자원을 명사로 두고 행위는 메서드로 표현합니다. 서버가 이전 요청을 기억하지 않는 무상태가 확장을 쉽게 만듭니다.

REST API 설계

REpresentational State Transfer. 리소스 중심으로 HTTP를 활용한 API 설계 원칙.

REST의 핵심 원칙

1. 리소스 기반 URL (명사)
   /users, /posts, /orders

2. HTTP 메서드로 행위 표현
   GET, POST, PUT, DELETE

3. 무상태 (Stateless)
   각 요청은 독립적, 서버에 상태 없음

4. 표현(Representation)
   JSON, XML 등으로 리소스 표현

URL 설계 규칙

CRUD 매핑

리소스: /users

POST   /users         → 생성 (201)
GET    /users         → 목록 (200)
GET    /users/1       → 상세 (200)
PUT    /users/1       → 전체 수정 (200)
PATCH  /users/1       → 부분 수정 (200)
DELETE /users/1       → 삭제 (204)

중첩 리소스

/users/1/posts       → 유저 1의 게시글
/users/1/posts/5     → 유저 1의 게시글 5
/posts/5/comments    → 게시글 5의 댓글

2단계까지만 중첩 권장
3단계 이상 → 쿼리 파라미터 사용

필터/정렬/페이징

응답 형식

// 성공 (목록)
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150
  }
}

// 성공 (단일)
{
  "data": { "id": 1, "name": "Kim" }
}

// 에러
{
  "error": {
    "code": "NOT_FOUND",
    "message": "User not found"
  }
}

버전 관리

URL 방식:  /api/v1/users (가장 일반적)
헤더 방식: Accept: application/vnd.api+v1

실무 체크리스트