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 설계 규칙
| 규칙 | 좋은 예 | 나쁜 예 |
|---|
| 명사 사용 | /users | /getUsers |
| 복수형 | /users | /user |
| 소문자 | /user-profiles | /UserProfiles |
| 계층 관계 | /users/1/posts | /getUserPosts |
| 동사 금지 | DELETE /users/1 | /deleteUser/1 |
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단계 이상 → 쿼리 파라미터 사용
필터/정렬/페이징
| 용도 | 요청 예 |
|---|
| 필터 | GET /users?role=admin&status=active |
| 정렬 | GET /users?sort=created_at&order=desc |
| 페이징 | GET /users?page=2&limit=20 |
| 검색 | GET /users?q=kim |
| 필드 선택 | GET /users?fields=id,name,email |
응답 형식
// 성공 (목록)
{
"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
실무 체크리스트
| 항목 | 설명 |
|---|
| 일관된 응답 형식 | data/error 래퍼 통일 |
| 적절한 상태 코드 | 200/201/204/400/404 |
| 페이지네이션 | 대량 데이터 필수 |
| Rate Limiting | 429 + Retry-After |
| 인증 | Authorization 헤더 |
| HATEOAS | (선택) 링크 포함 |