웹 개발에서 API를 디자인할 때 가장 중요한 부분 중 하나는 자원(Resource)의 표현과 엔드포인트(Endpoint) URL을 설계하는 것입니다. 올바른 자원 표현과 URL 설계는 API의 유지보수성, 확장성, 그리고 사용자 경험에 중요한 영향을 미칩니다.

자원의 표현

API에서 자원은 사용자가 액세스하거나 조작할 수 있는 모든 것을 나타냅니다. 일반적으로 데이터베이스의 엔터티(Entity)나 컬렉션(Collection)이 자원으로 표현됩니다. 예를 들어, 사용자, 주문, 제품 등이 될 수 있습니다.

JSON을 사용하여 자원을 표현할 때, 각 자원은 그 자원에 관련된 속성을 포함하는 객체로 표현됩니다. 예를 들어, 사용자 자원은 아래와 같이 표현될 수 있습니다.

{
  "id": 1,
  "username": "john_doe",
  "email": "john_doe@example.com"
}

URL 설계 원칙

명사만을 사용

URL은 동사보다는 명사로 구성되어야 합니다. 명사를 사용하면 API가 더 직관적이고 읽기 쉽습니다. 예를 들어, /users는 사용자 목록을 나타내고, /orders는 주문 목록을 나타내는 것이 좋습니다.

복수형 사용

컬렉션을 나타내는 URL은 복수형으로 사용하는 것이 일반적입니다. 사용자 목록을 가져오는 엔드포인트는 /users로 표현하는 것이 좋습니다.

계층 구조 표현

자원 간의 계층 구조가 있는 경우, URL에도 이를 반영하는 것이 좋습니다. 예를 들어, 특정 사용자의 주문 목록을 가져오는 경우 /users/{user_id}/orders와 같이 표현할 수 있습니다.

RESTful 설계

REST(Representational State Transfer)의 원칙을 따르는 것이 좋습니다. 이는 HTTP 프로토콜을 이용하여 자원을 처리하는 상태 전달 방식을 가리킵니다.

위의 설계 원칙을 고려하여 API의 자원 표현과 URL을 설계하면, API를 사용하는 개발자들이 쉽게 이해하고 활용할 수 있게 됩니다.

자원의 표현 방법과 URL 설계 원칙은 API 디자인에서 중요한 부분이므로, 이를 고려하여 일관성 있는 API를 구축할 수 있도록 노력해야 합니다.

Reference:

• https://restfulapi.net/resource-naming/
• https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm