RESTful API 설계 시 좋은 작명의 방법

[polyglot-k]

RESTful API 설계에서 URL(엔드포인트)을 작명하는 방법은 API의 사용성과 가독성을 높이는 데 중요한 요소입니다. 다음은 RESTful하게 URL을 작명하는 몇 가지 방법과 모범 사례입니다.

1. 명사 사용

• 명사를 사용하여 리소스를 표현: URL은 주로 리소스를 나타내는 명사로 구성되어야 합니다.
• 예시:
  • /products (모든 제품)
  • /users (모든 사용자)
  • /orders (모든 주문)

2. 자원 간 관계 표현

• 하위 자원: 상위 자원 아래의 하위 자원을 표현할 때는 슬래시(/)를 사용합니다.
• 예시:
  • /users/{userId}/orders (특정 사용자의 주문)
  • /products/{productId}/reviews (특정 제품의 리뷰)

3. HTTP 메서드와 결합

• HTTP 메서드로 동작 정의: URL은 리소스를 정의하고, HTTP 메서드는 해당 리소스에 대한 동작을 정의합니다.
  • GET: 리소스 조회
  • POST: 리소스 생성
  • PUT: 리소스 전체 수정
  • PATCH: 리소스 부분 수정
  • DELETE: 리소스 삭제

4. 쿼리 파라미터 사용

• 필터링 및 정렬: 쿼리 파라미터를 사용하여 검색, 필터링, 정렬 등의 기능을 제공할 수 있습니다.
• 예시:
  • /products?category=electronics (전자 제품 필터링)
  • /orders?status=pending (대기 중인 주문 필터링)

5. 버전 관리

• API 버전 관리: URL에 API 버전을 포함하여 변화에 유연하게 대응할 수 있습니다.
• 예시:
  • /api/v1/products (1버전 API)
  • /api/v2/products (2버전 API)

6. 복수형 및 단수형

• 복수형 사용: URL의 리소스는 일반적으로 복수형을 사용하여 여러 개의 리소스를 나타냅니다.
• 예시:
  • /products (모든 제품)
  • /users (모든 사용자)
• 단수형 사용: 특정 리소스를 가리킬 때 단수형을 사용할 수 있습니다.
• 예시:
  • /products/{productId} (특정 제품)
  • /users/{userId} (특정 사용자)

7. 일관성 유지

• 일관된 패턴 사용: URL 설계에서 일관된 패턴을 유지하면 사용자와 개발자 모두 이해하기 쉽습니다.
• 예시:
  • /api/v1/products
  • /api/v1/users

8. 의미 있는 이름 사용

• 의미 있는 URL: URL은 사용자가 쉽게 이해할 수 있는 이름으로 구성되어야 합니다. 리소스의 역할과 관계를 명확히 표현합니다.

예시 URL 설계

HTTP 메서드	URL	설명
GET	/api/v1/products	모든 제품 목록 조회
GET	/api/v1/products/{productId}	특정 제품 조회
POST	/api/v1/products	새 제품 등록
PUT	/api/v1/products/{productId}	특정 제품 정보 수정
DELETE	/api/v1/products/{productId}	특정 제품 삭제
GET	/api/v1/users/{userId}/orders	특정 사용자의 주문 조회
GET	/api/v1/orders?status=pending	대기 중인 모든 주문 조회

결론

RESTful API 설계에서 URL 작명 규칙은 사용자의 기대에 부응하고, API의 가독성과 유지 보수성을 높이는 데 중요한 역할을 합니다. 위의 원칙을 따르면 클라이언트와 서버 간의 통신이 명확하고 일관되며 직관적으로 이루어질 수 있습니다.