[Web] Rest URI 네이밍

1. What is a Resource?

 

REST 방식에서는 주요 데이터 표현, 개념을 리소스라고 한다. REST 방식에서 얻을 수 있는 정보들, 문서나 이미지, 특정 서비스 또는 다른 리소스들의 컬렉션 등을  리소스라고 한다.

 

리소스는 어떤 특정한 엔티티라기보다는 엔티티들의 집합과 개념적으로 매핑되어 있다고 이해할 수 있다.

 

1) Singleton and Collection Resources

 

리소스는 singleton 이 될 수도, collection 이 될 수도  있다.

 

예를 들어 customer 라는 엔티티가 있을 때, customer 는 싱글 리소스, customers 는 컬렉션 리소스가 된다. customers 는 '/customers' 로 customer 에 대해서는 '/customers/{customerId}' 와 같이 URI 를 매핑하여 구분할 수 있다.

 

 

2) Collection and Sub-collection Resources

 

리소스는 서브 리소스를 포함할 수 있다.

 

예를 들어 은행 시스템이 있다고 하면, 각 customer 가 accounts 라는 서브 리소스를 가질 수 있다. 이러한 경우 '/customers/{customerID}/accounts' 와 같이 서브 리소스 구조로 URN 을 구성할 수 있다.

 

이러한 방법으로 컬렉션 리소스인 accounts 에서 싱글 리소스인 account 에 접근하기 위해 '/customers/{customerID}/accounts/{accountID}' 으로 특정 account 에 접근할 수 있다.

 

 

3) URI

 

REST API 는 URI 를 리소스 주소로 사용한다. 개발자는 리소스를 REST API 로 클라이언트가 사용할 수 있도록 URI 를 설계한다. 이때 직관적으로 리소스의 이름을 설계한다면 API 를 사용하기 더 쉬워진다. 만약 직관적이지 않다면 API 를 사용하기 어렵고 이해하기 어렵게 된다.

 

 

2. 설계 예시

 

1) 명사 네이밍

 

RESTful URI 는 리소스를 다루는 작업, 행동이 아니라 리소스의 이름, 명사를 참조하도록 한다. 왜냐하면 명사는 동사는 가지지 못하는 속성, 영역이 있기 때문이다. 예를 들어 시스템의 유저, 유저의 정보 등과 같이 계층을 가지고 다른 리소스를 포함할 수 있다.

 

이러한 리소스의 타입을 더 명확하게 하기 위해서, document, collection, store 그리고 controller 의 4가지 타입으로 구분할 수 있다.

 

- document

 

document 리소스는 객체 인스턴스나 데이터베이스 데이터와 같은 유일 개념이다.

REST 방식에서 리소스의 컬렉션 내부의 하나의 리소스로 생각하면 된다. document 의 상태 표현은 일반적으로 값과 다른 연관된 리소스로의 링크를 모두 포함하고 있다.

 

document 리소스를 표현하기 위해서는 단수 표현으로 이름을 정한다.

 

http://api.example.com/device-management/managed-devices/{device-id}
 http://api.example.com/user-management/users/{id}
 http://api.example.com/user-management/users/admin

 

- collection

 

collection 리소스는 리소스들의 server-managed directory 이다.

클라이언트가 리소스들을 컬렉션에 추가하기를 요청할 수 있다. 이때 새로운 리소스를 생성할지 아닌지는 collection 리소스에게 달려있다. collection 리소스는 포함할 리소스를 선택하고 포함된 리소스들의 URI 를 결정한다.

 

collection 리소스를 표현하기 위해서는 복수 표현으로 이름을 정한다.

 

http://api.example.com/device-management/managed-devices
http://api.example.com/user-management/users
http://api.example.com/user-management/users/{id}/accounts

 

- store

 

store 리소스는 client-managed 리소스 저장소이다. store 리소스는 API 를 사용하는 client 가 리소스를 입력, 출력, 삭제 등을 수행할 수 있도록 한다.

 

store 는 절대로 새로운 URI들을 생성하지 않는다. 대신 각각의 저장된 리소스는 개별의 URI 를 가진다. 이들은 초기에 store 에 입력될때 client 에서 결정되어 들어온다.

 

store 리소스를 표현하기 위해서 URI 에서는 복수형 이름을 사용한다.

 

http://api.example.com/song-management/users/{id}/playlists

 

- controller

 

controller 리소스 절차, 프로세스의 개념을 규격화한다. controller 리소스는 실행 가능한 함수와 같이 매개변수와 반환 값, 입력값과 출력값을 가지고 있다.

 

controller 리소스를 표현하기 위해서는 동사를 사용한다.

 

http://api.example.com/cart-management/users/{id}/cart/checkout
http://api.example.com/song-management/users/{id}/playlist/play

 

2) Consistent naming convention

 

consistent reousrce naming convention 을 과 URI 형식을 통해서 좋은 가독성과 유지보수하기 쉬운 API 를 설계할 수 있다. 네에밍 룰을 작성할 때 아래에 있는 가이드들을 참고하면 좋은 도움이 될 수 있다.

 

- 계층 구조의 관계를 표현할 때 '/' 를 사용한다.

'/' 기호는 URI 의 path 위치를 표현할 때 사용하는데 이는 리소스들의 계층 관계를 표현한다.

- 마지막 '/' 는 제외한다.

URI 의 마지막 문자로 '/' 를 사용하게 되면 실제 의미가 없는 값일 뿐 아니라 많은 혼란을 준다. 그렇기 때문에 URI 에서는 마지막 슬래시는 생략하는게 좋다.

- URI 의 가독성 향상을 위한 하이픈 '-' 사용.

긴 이름을 사용할 때에 가독성을 위해서 하이픈을 사용한다.

- underscore '_' 는 사용을 자제한다.

하이픈 대신에 언더스코어를 사용할 수 있다. 하지만 언더스크린은 특정한 화면이나 브라우저에서는 잘 식별되지 않아 가독성을 떨어트릴 수 있다. 혼란을 줄이기 위해서는 언더스코어 대신 하이픈을 사용하는 것이 좋다.

- URI 에서 소문자 사용

편의를 위해서 URI 경로에서는 소문자를 사용하는 것이 선호된다.

 

3) file extensions 제외

 

파일의 확장자는 보기에 좋지 않을뿐더러 다른 장점을 가지고 있지 않다. URI 의 길이를 줄이기 위해서 확장자를 제외하는 것이 훨씬 좋다. 이를 유지해야할 특별한 이유가 없다.

 

만약 해당 API 의 media type 을 강조하고 싶다면 파일 확장자를 통해 표현하기 보다는 Content-type 헤더를 사용하여 메시지 바디의 내용을 지정하는 것이 낫다.

 

4) CRUD 함수 사용 금지

 

URI 는 CRUD 함수를 가르키기 위해서 사용하는 것이 아니다. URI 는 특정한 리소스를 식별하기 위함이지 특정 동작을 위함이 아니다.

 

각각의 동작을 URI 에 표현하기 보다는 HTTP request 함수를 통해 CRUD 함수를 각각 매핑하여 표현하는 것이 더 좋은 방법이다.

 

5) URI query component 사용

 

때로 특정 리소스를 요청할 때, 정렬이나 필터링이 된 값들이 필요한 경우가 있다. 이러한 요청을 위해서 새로운 API 를 추가하기 보다는 이에대해서 입력 매개변수를 쿼리로 받아서 해결하도록 한다.

 

 

[reference]

• https://restfulapi.net/resource-naming/