깔끔한 URL 패턴을 위한 REST Resource Naming Guide

URL 패턴을 내 마음대로 지었다가 지적받았다. 조언에 따라서 REST API 의 URL 가이드를 참고하여 정리해본다.

해석이 틀리거나 할 수 있다.

1. A resource can be a singleton or a collection.
하나의 리소스는 싱글턴 또는 컬랙션이 될 수 있다.

singlton: 단 하나만 지칭할 때
collection: 여러개를 합쳐서 지징할 때

예를 들어 coustomers 는 컬랙션 리소스이며 costomer 는 싱글턴 리소스이다.
coustomers 컬랙션 리소스는 /customers 라는 URI 를 사용한다.
이에 따라서, customers/{customerId} 라는 URI 를 이용하여 customer 라는 리소스를 식별할 수 있다.

2. A resource may contain sub-collection resources also
리소스는 sub-collection 리소스를 포함할 수 있다.
예를들어, 특정 customer 의 accounts 는 /customers/{customerId}/accounts 로 식별할 수 있다.

REST APIS 는 URIs : Uniform Resource Identifiers 를 사용하여 리소스를 다룬다.
이러한 방식으로 URI 명을 잘 짓게되면, API는 직관적이로 사용하기 편리하게 된다.

REST Resource 이름 짓기

Use nouns to represent resources. (리소스를 표현하기 위해서 명사 를 사용)
RESTful URI 는 반드시 리소스 그 자체를 언급해야 하며, 리소스의 행동을 언급해서는 안된다.
예를 들면, 아래와 같은 리소스들이 있을 때 URI는 는 다음과 같이 디자인 될 수 있다.

• Users of the system
• User Accounts
• Network Devices etc.

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

1. document 리소스
Use 'singular' name to denote document resource archetype.
(문서의 유형을 나타낼 때는 '단수'를 사용.)

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

2. collection 리소스
Use the 'plural' name to denote the collection resource archetype. (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

3. store 리소스
Use 'plural' name to denote store resource archetype.
저장에 관한 요청은 클라이언트가 관리하는 리소스 저장소이다. 따라서 '복수'를 사용한다.
클라이언트가 어떠한 곡을 자신의 playlists 에 넣어서 관리하고 싶을 때, put, delete 등의 요청을 보내어, playlists에 추가하거나 다시 제거하거나 할 수 있다.

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

4. controller 리소스
컨트롤러 리소스는 실행 가능한 기능과 함께 파라미터 혹은 리턴 값으로 이름 짓는다.
이 때는 '동사' 를 사용한다.

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

URI의 키는 일관성

최대의 가독성과 유지보수를 위해서 일관된 리소스 이름 지정 규칙과 URI 형식을 지키기.
아래는 그러한 URI 설계를 위한 몇 가지 힌트이다.

1. Use forward slash (/) to indicate hierarchical relationships
계층 구조를 표현하기 위해서 / 를 사용한다.

http://api.example.com/device-management
http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices/{id}
http://api.example.com/device-management/managed-devices/{id}/scripts
http://api.example.com/device-management/managed-devices/{id}/scripts/{id}

2. Do not use trailing forward slash (/) in URIs
끝에 / 가 따라붙지 않도록 한다.

http://api.example.com/device-management/managed-devices/
http://api.example.com/device-management/managed-devices 	/*This is much better version*/

3. Use hyphens (-) to improve the readability of URIs
가독성을 위해서 - 을 사용하기. 긴 문자열이나, 읽히기 어려운 문자열에 대하여 - 처리를 하여 가독성을 높이는 것을 고려해볼 수 있다.

http://api.example.com/inventory-management/managed-entities/{id}/install-script-location  //More readable
http://api.example.com/inventory-management/managedEntities/{id}/installScriptLocation  //Less readable

4. Do not use underscores ( _ )
언더바의 사용은 피한다. 응용 프로그램의 글꼴에 따라서 밑줄(_) 문자가 부분적으로 가려지거나 일부 브라우저 화면에서 완전히 가려질 수 있다.

5. Use lowercase letters in URIs
편리함 + Convention 을 지키기 위해서 소문자를 사용한다.

6. Do not use file extentions
파일 확장자를 포함시키지 않도록 한다.
파일 확장자를 URI에 포함시키는 것은 어떠한 장점도 없다. 오히려 URI가 길어질 뿐이다.

http://api.example.com/device-management/managed-devices.xml  /*Do not use it*/
http://api.example.com/device-management/managed-devices 	/*This is correct URI*/

Never use CRUD function names in URIs

URI를 사용해서 CRUD 기능이 수행되었음을 표시해서는 안된다.
URI는 자원에 대한 어떠한 행동을 나타내는 것이 되어서는 안되고, 자원을 독립적으로 식별하는 방식으로 사용되어야 한다. 어떤 CRUD 기능이 수행되는지 표시하기 위해서는 HTTP 요청 방법을 사용해야 한다.

HTTP GET http://api.example.com/device-management/managed-devices  //Get all devices
HTTP POST http://api.example.com/device-management/managed-devices  //Create new Device

HTTP GET http://api.example.com/device-management/managed-devices/{id}  //Get device for given Id
HTTP PUT http://api.example.com/device-management/managed-devices/{id}  //Update device for given Id
HTTP DELETE http://api.example.com/device-management/managed-devices/{id}  //Delete device for given Id

Use query component to filter URI collection

쿼리스트링을 이용하는 것을 고려해라.
특정 리소스의 속성을 기준으로 정렬, 필터링을 자주하게 될 수 있다.
이를 위해서 새로운 API 를 만들기 보단, 입력 매개변수를 쿼리스트링에 전달하도록 한다.