REST API 설계 완전 가이드
기본 규칙
- URL은 리소스를 나타내며, 동사가 아닌 명사 사용
- 리소스는 복수형으로 사용
- 계층 관계는 '/'로 표현
- URL 마지막에 '/' 포함하지 않음
- 언더바(_) 대신 하이픈(-) 사용
- 소문자 사용
리소스 네이밍
# 좋은 예시
/api/v1/posts
/api/v1/users/{id}/comments
# 나쁜 예시
/api/v1/getPosts # 동사 사용
/api/v1/user_comments # 언더스코어 사용
/api/v1/createNewUser # 행위 표현
HTTP 메서드
| 메서드 |
용도 |
예시 |
| GET |
리소스 조회 |
GET /users |
| POST |
리소스 생성 |
POST /users |
| PUT |
리소스 전체 수정 |
PUT /users/123 |
| PATCH |
리소스 부분 수정 |
PATCH /users/123 |
| DELETE |
리소스 삭제 |
DELETE /users/123 |
HTTP 메서드 상세 사용
# 컬렉션 관련
GET /posts # 목록 조회
POST /posts # 새 포스트 생성
# 특정 리소스 관련
GET /posts/{id} # 특정 포스트 조회
PUT /posts/{id} # 특정 포스트 전체 수정
PATCH /posts/{id} # 특정 포스트 부분 수정
DELETE /posts/{id} # 특정 포스트 삭제
# 하위 리소스 관련
GET /posts/{id}/comments # 특정 포스트의 댓글 목록
POST /posts/{id}/comments # 특정 포스트에 댓글 추가
쿼리 파라미터 규칙
# 페이지네이션
/api/v1/posts?page=2&size=10
# 필터링
/api/v1/products?category=electronics&price_min=100
# 검색
/api/v1/users?search=john
# 정렬
/api/v1/users?sort=name:asc,age:desc
상태 코드 상세 사용
# 2XX - 성공
200 OK # 요청 성공
201 Created # 리소스 생성 성공
204 No Content # 성공했지만 반환할 데이터 없음
# 4XX - 클라이언트 에러
400 Bad Request # 잘못된 요청 구문
401 Unauthorized # 인증 필요
403 Forbidden # 권한 부족
404 Not Found # 리소스 없음
409 Conflict # 리소스 충돌 (중복 등)
# 5XX - 서버 에러
500 Internal Server Error # 서버 에러
503 Service Unavailable # 서버 일시적 사용 불가
응답 데이터 구조
# 단일 리소스 응답
{
"data": {
"id": 1,
"title": "제목",
"content": "내용",
"created_at": "2024-12-17T10:00:00Z"
}
}
# 컬렉션 응답
{
"data": [{
"id": 1,
"title": "제목1"
}, {
"id": 2,
"title": "제목2"
}],
"meta": {
"total": 100,
"page": 1,
"size": 10
}
}
# 에러 응답
{
"error": {
"code": "INVALID_PARAMETER",
"message": "Invalid parameter value",
"details": {
"field": "email",
"reason": "Invalid email format"
}
}
}
버전 관리
/api/v1/users
/api/v2/users
API 문서화 예시
## 사용자 생성 API
### 요청
POST /api/v1/users
### 요청 헤더
Content-Type: application/json
Authorization: Bearer {token}
### 요청 본문
{
"name": "string",
"email": "string",
"password": "string"
}
### 응답
201 Created
{
"data": {
"id": "number",
"name": "string",
"email": "string",
"created_at": "datetime"
}
}
### 에러
- 400: 잘못된 요청
- 401: 인증 필요
- 409: 이메일 중복
보안 관련
- 민감한 데이터는 URL에 포함하지 않음
- 인증이 필요한 엔드포인트는 항상 HTTPS 사용
- API 키나 인증 토큰은 헤더에 포함
- Rate Limiting 적용 고려
HATEOAS 링크
{
"data": {
"id": 1,
"title": "게시글",
"_links": {
"self": "/api/v1/posts/1",
"comments": "/api/v1/posts/1/comments",
"author": "/api/v1/users/1"
}
}
}
이러한 규칙들을 일관되게 적용하면 이해하기 쉽고 사용하기 편한 API를 만들 수 있습니다.
댓글