REST(Representational State Transfer)는 HTTP를 기반으로 하는 아키텍처 스타일로, 리소스에 대한 접근과 상태 전이를 다룹니다. REST API를 설계할 때는 URI(Uniform Resource Identifier)의 구조를 명확히 정의해야 합니다.

URI 설계 원칙

1. 리소스 식별

리소스는 개별적으로 식별 가능해야 합니다. 각 리소스는 URI로 고유하게 식별되어야 합니다.

2. 명사 사용

URI에는 동사보다는 명사를 사용해야 합니다. 예를 들어, 사용자 리소스에 접근하기 위한 URI는 /users와 같이 사용해야 합니다.

3. 계층 구조 활용

리소스 간에 계층 구조가 있을 경우, 계층 구조를 활용하여 URI를 설계해야 합니다. 예를 들어, 특정 사용자의 주문 목록에 접근하기 위한 URI는 /users/{userId}/orders와 같이 설계할 수 있습니다.

4. 슬래시 사용

URI 경로의 마지막에 슬래시를 사용하지 않아야 합니다. 슬래시를 사용할 경우, 동일한 리소스를 가리키므로 일관성을 유지하기 위해 슬래시를 사용하지 않아야 합니다.

5. 행위 표현을 피하기

URI에는 동작을 나타내는 단어나 동사를 사용하면 안 됩니다. 대신, HTTP 메서드(GET, POST, PUT, DELETE 등)를 사용하여 리소스에 대한 동작을 나타내어야 합니다.

URI 설계 예시

// 사용자 목록 조회
GET /users

// 특정 사용자 정보 조회
GET /users/{userId}

// 특정 사용자의 주문 목록 조회
GET /users/{userId}/orders

// 새로운 주문 생성
POST /orders

이러한 URI 설계 방법을 따르면 REST API가 일관적이고 직관적으로 사용될 수 있습니다.

결론

REST API를 위한 URI를 설계할 때는 각 URI가 리소스를 명확하게 식별하고, 계층 구조를 활용하여 일관성 있게 설계해야 합니다. 명사를 사용하고, 행위를 나타내는 단어를 피함으로써 RESTful한 URI를 구성할 수 있습니다.

참고문헌: MDN Web Docs