[WEB] REST API - URI 설계 규칙

결국 REST API의 핵심을 정리하자면 다음과 같다.

 

• 클라이언트 - 서버 간의 통신 방식 중 하나이다.
• 자원을 이름으로 구분한다.
• 자원과 행위를 분리하여 HTTP 메서드로 표현한다.
• 자원의 상태를 서로 주고 받는다.

 

URI 란?

URI(Uniform Resource Identifier)란, 직역하면 "통합 자원 식별자" 이다.

 

Uniform : 자원을 식별하는 통합된 방식

 

Resource : 웹 브라우저 파일이나 이미지, 기타 리소스(식별 가능한 모든 자원)

 

Identifier : 식별자

 

즉, URI란 자원을 식별하기 위한 시퀀스이며, 이는 REST에서 자원을 잘 식별하여 처리하기 위해 사용한다.

 

따라서, 개발자는 URI를 잘 네이밍해야 좋은 API를 만들 수 있고, 이를 위해서는 다음의 URI 설계 규칙을 지켜야 한다.

 

URI 설계 규칙

1.  명사를 사용해서 자원을 표현한다.

• /product : 상품의 정보
• 예외적으로 controller의 경우에는 동사를 허용한다.

 

2. 자원 간 계층 관계를 표현하기 위해 "/"를 사용한다.

• /product/3 : 3번 상품의 정보
• url 경로 마지막에는 "/"를 사용하지 않는다.

 

3. URI의 가독성 향상을 위해 "-"을 사용한다.

• /baseballgamemanager (x)
• /baseball-game-manager (o)
• underscore(_)는 가급적 사용하지 않는다.

 

4. 파일 확장자(ex .jpg) 등을 사용하지 않는다.

 

5. URI에 HTTP Method명을 기재하지 않는다.

 

6. 자원의 필터링을 위해 새로운 API를 만들지 않는다.

• Query String을 이용한다.
• EX. 음식 상품을 오름차순으로 정렬하는 URI
  
  • /products?type=food&sort=name,asc

7.  다음과 같은 경우에는 복수명사를 사용하자

• 서버가 관리하는 리소스 디렉터리(collection)의 경우 : 서버가 리소스의 URI를 생성하고 관리하는 경우
• ex:  /members

• 클라이언트 관리하는 자원 저장소(store)의 경우 : 클라이언트가 리소스의 URI을 아는 경우
• ex:  /files

 

출처

• https://www.youtube.com/watch?v=xWA1eTPSzDE