REST vs RESTful
REST는 "이렇게 하면 좋은 설계다"는 원칙이고,
RESTful은 "그 원칙을 잘 지켜 만든 API"를 말합니다.
| 구분 | REST | RESTful |
|---|---|---|
| 의미 | 아키텍처 스타일 (설계 원칙) | REST를 잘 지킨 API 구현 방식 |
| 성격 | 개념 (철학, 이론) | 구현 (적용 수준) |
| 역할 | 어떤 방식으로 시스템을 설계해야 하는가 | 그 설계 원칙을 실천한 API를 어떻게 만들었는가 |
| 주체 | 이론적 정의 (Roy Fielding 논문) | 개발자가 실제로 만든 API 설계 |
| 예시 | 클라이언트-서버, Stateless, URI 기반 리소스 식별 | /users, /users/1 같은 REST 기반 API 설계 |
비유하면?
- REST: 운동은 건강에 좋고, 식단 조절이 필요하며, 꾸준히 해야 한다는 "운동의 원칙"
- RESTful: 그 원칙을 잘 지켜서 매일 운동하고 식단도 지키는 사람 = RESTful한 사람
즉, REST는 철학이고, RESTful은 실천입니다.
REST의 6가지 제약 조건
Roy Fielding이 정의한 REST의 핵심 제약 조건들:
1. 클라이언트-서버 (Client-Server)
- 사용자 인터페이스와 데이터 저장소를 분리
- 서로의 역할이 명확히 분리되어야 함
2. 무상태성 (Stateless)
- 각 요청은 독립적이어야 하며, 서버는 클라이언트 상태를 저장하지 않음
- 모든 필요한 정보는 요청에 포함되어야 함
3. 캐시 가능 (Cacheable)
- 응답은 캐시 가능한지 명시되어야 함
- 성능 향상을 위해 캐싱 활용
4. 계층화된 시스템 (Layered System)
- 클라이언트는 최종 서버와 직접 연결되었는지 중간 서버를 거쳤는지 알 수 없음
- 로드 밸런서, 프록시 등 중간 계층 활용 가능
5. 통일된 인터페이스 (Uniform Interface)
- 리소스 식별, 표현을 통한 리소스 조작, 자기 서술적 메시지, HATEOAS
6. 주문형 코드 (Code on Demand) - 선택사항
- 필요시 클라이언트로 실행 가능한 코드 전송
RESTful API의 세부 조건
| 조건 | 좋은 예시 | 나쁜 예시 |
|---|---|---|
| 리소스는 URI로 표현 | /users, /posts/1 | /getUserById |
| HTTP 메서드는 행위를 표현 | GET, POST, PUT, DELETE | 모든 요청에 POST 사용 |
| URI에는 동사 대신 명사 사용 | /users ✅ | /getUser ❌ |
| 계층 구조 표현 | /users/1/posts/5 | /user-post-5 |
| 상태 코드 적절히 활용 | 200, 201, 404, 500 | 항상 200 반환 |
| 일관된 네이밍 규칙 | kebab-case 또는 camelCase 통일 | 혼재 사용 |
| 리소스는 복수형 명사 사용 | /users, /users/1 | /user, /user/1 (컬렉션 의미가 불분명) |
1. 리소스는 URI로 표현한다.
- 리소스는 고유한 식별자 역할을 하는 URI로 표현해야 한다.
- 예:
/users,/posts/1등 - 잘못된 예:
/getUserById(행위가 포함됨)
2. HTTP 메서드는 행위를 표현한다.
- GET: 리소스 조회
- POST: 리소스 생성
- PUT/PATCH: 리소스 수정
- DELETE: 리소스 삭제
- 잘못된 예: 모든 요청을 POST로 처리
3. URI에는 동사 대신 명사를 사용한다.
- REST는 "자원 중심"이므로 URI에는 명사를 사용한다.
- 예:
/users,/orders/123 - 잘못된 예:
/getUser,/createOrder등
4. URI는 계층 구조로 표현한다.
- 리소스 간의 포함 관계나 종속 관계는 URI 계층 구조로 나타낸다.
- 예:
/users/1/posts/5(1번 유저의 5번 게시글) - 잘못된 예:
/user-post-5
5. HTTP 상태 코드를 적절히 사용한다.
- 성공:
200 OK, 201 Created - 실패:
400 Bad Request, 404 Not Found, 500 Internal Server Error등 - 잘못된 예: 항상
200 OK만 반환
6. 일관된 네이밍 규칙을 사용한다.
- URI 표기 방식은 통일성 있게 유지한다.
- 예: Kebab-case 또는 camelCase 중 하나로 통일
- 잘못된 예:
/user-profile,getUserInfo(혼용)
7. 복수형 명사를 사용한다.
- 리소스는 컬렉션의 의미이므로 복수형 명사를 사용한다.
- 예:
/users→ 사용자 목록,/users/1→ 1번 사용자 - 잘못된 예:
/user,/user/1(컬렉션 의미가 불분명)
RESTful하지 않은 설계 vs RESTful한 설계
RESTful하지 않은 설계
GET /getUser?id=1
POST /updateUser?id=1
GET /getUserPosts?userId=1
POST /deleteUser?id=1
DELETE /user/delete/1
PUT /users/1/activateRESTful한 설계
GET /users/1
PUT /users/1
GET /users/1/posts
DELETE /users/1
PATCH /users/1 (상태 변경은 body에서)RESTful API 응답 형태 예시
성공 응답
// GET /users/1
{
"id": 1,
"name": "김개발",
"email": "dev@example.com",
"created_at": "2024-01-01T00:00:00Z"
}컬렉션 응답
// GET /users
{
"data": [
{
"id": 1,
"name": "김개발",
"email": "dev@example.com"
}
],
"pagination": {
"page": 1,
"limit": 10,
"total": 50
}
}에러 응답
// 404 Not Found
{
"error": {
"code": "USER_NOT_FOUND",
"message": "사용자를 찾을 수 없습니다",
"details": {
"user_id": 999
}
}
}참고: RESTful API 설계 체크리스트
URI 설계
- 명사 사용 (동사 ❌)
- 소문자 사용
- 하이픈(-) 사용, 언더스코어(_) 지양
- 계층 관계 명확히 표현
- 컬렉션은 복수형, 단일 리소스는 단수형
HTTP 메서드 활용
- GET: 조회
- POST: 생성
- PUT: 전체 수정
- PATCH: 부분 수정
- DELETE: 삭제
응답 설계
- 적절한 HTTP 상태 코드 사용
- 일관된 응답 형태 유지
- 에러 응답에 충분한 정보 포함
- 페이지네이션 정보 제공
보안 및 기타
- HTTPS 사용
- 인증/인가 처리
- 버전 관리 전략
- API 문서화
donggyun_ee