Resource?

• REST에서 주요한 정보를 Resource라고 한다. 파일 이미지 뿐만 아니라 우리가 일반적으로 교환하는 모든 정보를 포함한다.

Singleton and Collection Resource

• 하나의 자원은 싱글톤 또는 컬렉션이 될 수 있다.
• Singleton : 단 하나의 자원, Collection : 여러 개가 합쳐진 자원
• 예를들어 customers는 컬렉션이며 customer는 싱글톤이다. 이에 따라서, customers/customerId라는 URI를 이용하여 customer라는 싱글톤 자원을 식별할 수 있다.

Collection and Sub-collection Resources

• Resource는 sub-collection resource를 포함시킬 수 있다.
• 예를들어, 특정 customer 의 accounts 는 /customers/{customerId}/accounts 로 식별할 수 있다.

URI

• REST API는 Resource를 다룰 때 Uniform Resource Identifiers(URIs)를 사용한다.
• 이름이 잘 지정된 URI는 클라이언트가 사용하기에 직관적이고 사용하기 쉽게 보인다.

Best Practices

• 자원을 표현하기 위해 명사를 사용
• Restful한 URI는 반드시 사물(명사)를 적어야 하며, 동작(동사)를 적어서는 안된다.
• 예를 들면, 아래와 같은 자원들이 있을 때 URI는 다음과 같이 디자인 된다.

Document Resource

• 문서의 유형을 나타낼 때는 단수 사용
  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 Resource

• Collections 단위의 리소스를 표시할 때는 복수 사용
  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 Resource

• 복수를 사용한다.
• 클라이언트가 어떠한 곡을 자신의 playlists에 넣어서 관리하고 싶을 때, put, delete 등 요청을 보내 추가하거나 제거할 수 있다.
  http://api.example.com/song-management/users/{id}/playlists

Controller Resource

• 실행 가능한 기능과 함께 파라미터 또는 리턴 값으로 이름을 짓는다. 이 때는 동사를 사용한다.
  http://api.example.com/cart-management/users/{id}/cart/checkout
  http://api.example.com/song-management/users/{id}/playlist/play

URI의 키는 일관성있게

• 계층 구조를 표현하기 위해 슬래시를 사용하기.
• 단 URI끝에는 붙이지 않는다.
  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}

가독성을 높이기 위해 하이픈을 사용하기

• 긴 문자열이나 읽기 어려운 문자열에 하이픈을 붙여 가독성을 높인다.
  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

언더스코어(_) 사용하지 않기

• 일부 브라우저 환경에 따라 언더스코어가 가려질 수 있다.

URI에 소문자 사용하기

• Convention + 편리함을 지키기 위해 소문자를 사용한다.

파일 확장자 포함시키지 않기

• 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/

쿼리 스트링을 사용하기.

• 특정 자원의 속성을 기준으로 정렬, 필터링을 자주 할 경우에 새로운 API를 만들기 보단, Input을 쿼리 스트링에 전달하게 설계한다.

절대 CRUD 함수를 URI에 사용하지 않기

• URI는 자원에 대한 어떠한 행동을 나타내는 것이 아니라, 자원을 독립적으로 식별하는 방식으로 사용되어야 한다.
• 어떤 CRUD 기능이 수행되는지 표시하려면 HTTP Request Method를 사용해서 표시한다.

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