1. 리소스 기반 URL
API는 동작(액션)보다 리소스를 중심으로 설계
리소스는 일반적으로 복수형 명사로 표현
올바른 예
- /users: 사용자 목록
- /products: 제품 목록
잘못된 예
- /getUsers: 동작 중심
- /create-product: 동작 중심
2. HTTP 메서드 사용
RESTful API는 HTTP 메서드를 활용해 동작을 표현
| HTTP 메서드 | 의미 | 예시 URL | 동작 |
|---|---|---|---|
| GET | 리소스 조회 | /users | 모든 사용자 조회 |
| GET | 리소스 상세 조회 | /users/{id} | 특정 사용자 조회 |
| POST | 리소스 생성 | /users | 사용자 생성 |
| PUT | 리소스 전체 수정 | /users/{id} | 특정 사용자의 전체 데이터 수정 |
| PATCH | 리소스 부분 수정 | /users/{id} | 특정 사용자의 일부 데이터 수정 |
| DELETE | 리소스 삭제 | /users/{id} | 특정 사용자 삭제 |
3. 계층 구조 표현
URL은 리소스 간의 관계를 계층적으로 표현
예시
- /users/{userId}/orders: 특정 사용자의 주문
- /orders/{orderId}/items: 특정 주문의 아이템 목록
4. 소문자 사용
URL은 항상 소문자로 작성
대소문자를 구분하지 않는 것이 일반적이지만, 관례적으로 소문자를 사용
올바른 예
- /users
- /products
잘못된 예
- /Users
- /Products
5. 언더스코어(_) 대신 하이픈(-) 사용
가독성을 높이기 위해 언더스코어 대신 하이픈을 사용
올바른 예
- /user-profiles
잘못된 예
- /user_profiles
6. 쿼리 파라미터 사용
정렬, 필터링, 페이징 등의 동작에는 쿼리 파라미터를 사용
예시
- /users?role=admin: 특정 역할을 가진 사용자 조회
- /products?page=2&size=10: 페이징 처리된 제품 목록
7. 파일 확장자 사용 금지
RESTful API에서는 파일 확장자를 URL에 포함X
대신 Accept 헤더를 사용해 형식을 지정합니다.
올바른 예
- GET /users + Accept: application/json
잘못된 예
- /users.json
8. 리소스 식별자는 명확하고 간결하게
리소스의 고유 식별자는 URL 경로에 포함
예시
- /users/123: 사용자 ID가 123인 사용자
- /products/456: 제품 ID가 456인 제품
9. 버전 관리
API 버전은 URL에 명시하거나 헤더를 사용
URL로 버전을 명시하는 방식이 일반적
URL로 버전 명시
- /v1/users
- /v2/products
헤더로 버전 명시
GET /users
Accept: application/vnd.example.v1+json10. 상태나 동작을 URL에 포함하지 말기
상태나 동작은 URL 대신 HTTP 메서드나 쿼리 파라미터로 표현
잘못된 예
- /users/activate: 동작 포함
- /orders/completed: 상태 포함
올바른 예
- PATCH /users/{id}: 활성화 상태로 변경
- GET /orders?status=completed: 완료된 주문만 조회
11. RESTful URL 설계 체크리스트
- 리소스 중심 설계
- 명사 기반 URL
- 소문자만 사용
- 복수형 사용
- HTTP 메서드 활용
- 계층 구조 명확히 표현
- 쿼리 파라미터로 동작 및 필터링 처리
- 파일 확장자 배제
- API 버전 관리 적용
BackEnd develope