📘 RESTful API 네이밍 규칙

RESTful API를 설계할 때, 일관성과 가독성을 높이기 위해 다음과 같은 네이밍 규칙을 따르는 것이 중요.
이를 통해 유지보수성과 확장성을 크게 향상시킬 수 있음

1. 🔤 리소스는 명사로 표현 (동사 X)

리소스(데이터 객체)는 명사로 표현합니다. 동사 대신 명사로 URL을 작성하는 것이 RESTful API의 기본 원칙입니다.

올바른 예시: /users, /items, /orders
잘못된 예시: /getUsers, /createItem, /deleteOrder

2. 🚀 HTTP 메소드를 활용한 의미 전달

동작(행동)은 HTTP 메소드로 표현하고, 경로에 동사를 넣지 않습니다.

GET: 리소스 조회 (예: GET /users)
POST: 리소스 생성 (예: POST /users)
PUT/PATCH: 리소스 업데이트 (예: PUT /users/{id})
DELETE: 리소스 삭제 (예: DELETE /users/{id})

예시:

GET /users: 모든 유저 목록 조회
GET /users/{id}: 특정 유저 조회
POST /users: 새로운 유저 생성
PUT /users/{id}: 유저 정보 업데이트
DELETE /users/{id}: 유저 삭제

3. 🔢 복수형 사용

리소스 이름은 항상 복수형을 사용합니다. 이는 하나 이상의 리소스를 다룰 수 있기 때문에 명확성을 높여줍니다.

올바른 예시: /users, /items, /products
잘못된 예시: /user, /item, /product

4. 🏷️ 경로에 동작이 아닌 리소스 식별자를 포함

경로에 동작을 명시하지 말고, 대신 리소스 식별자를 경로에 포함시킵니다.

예시:
- GET /orders/123: 주문 ID가 123인 주문을 조회
- PUT /users/456: 유저 ID가 456인 유저 정보 업데이트
- DELETE /products/789: 제품 ID가 789인 제품 삭제

5. 🗂️ 하위 리소스는 계층적으로 표현

하위 리소스(예: 유저의 주문)는 계층적 경로로 표현합니다. 이는 리소스 간의 관계를 명확하게 표현하는 데 도움이 됩니다.

예시:
- GET /users/123/orders: 유저 ID가 123인 사용자의 주문 목록 조회
- GET /users/123/orders/456: 유저 ID가 123인 사용자의 주문 ID가 456인 주문 상세 조회

6. 🔡 소문자 사용

경로에는 소문자만 사용합니다. 대소문자 혼용을 피하면 실수로 인한 오류를 줄일 수 있습니다.

올바른 예시: /users, /items
잘못된 예시: /Users, /Items

7. ➖ 하이픈(-)을 사용해 단어 구분

경로에서 단어를 구분할 때는 **하이픈(-)**을 사용합니다. 언더스코어(_)는 잘 사용되지 않으며, 대소문자를 구분하지 않기 때문에 하이픈이 가독성이 더 좋습니다.

올바른 예시: /user-profiles, /order-items
잘못된 예시: /user_profiles, /orderItems

8. 🛠️ HTTP 상태 코드를 적절히 사용

API 응답에서 적절한 HTTP 상태 코드를 반환하는 것도 중요합니다.

200 OK: 성공적인 조회
201 Created: 성공적인 리소스 생성
204 No Content: 성공적인 삭제
400 Bad Request: 잘못된 요청
404 Not Found: 리소스를 찾을 수 없음
500 Internal Server Error: 서버 오류

9. 🔍 필터링, 정렬, 페이징에는 쿼리 파라미터 사용

필터링, 정렬, 또는 페이징 작업이 필요할 때는 쿼리 파라미터를 사용합니다.

예시:
- GET /users?role=admin: 역할이 'admin'인 사용자 필터링
- GET /products?sort=price&order=desc: 가격 기준으로 내림차순 정렬
- GET /items?page=2&limit=50: 2페이지에 50개의 항목 가져오기