resource란?

REST에서 resource란 기본 데이터 표현으로 일관된 REST resource 명명 전략을 갖는 것은 장기적으로 최고의 설계 결정 중 하나일 것입니다.

리소스는 특정 시점에 해당하는 엔티티가 아니라 엔티티 집합에 대한 개념적 매핑입니다.
— Roy Fielding’s dissertation

1. Singleton & Collection

리소스는 싱글톤 또는 컬렉션인데, 이때 싱글톤은 customer이고, customers는 리소스입니다.
/customers/{customerId}와같은 방법을 사용해 컬렉션 리소스를 식별할 수 있습니다.

2. Collection & Sub-collection

리소스에는 하위 컬렉션 리소스도 포함될 수 있습니다.
customers/{customerId}/accounts와 같은 방식으로 컬렉션 리소스 내부에 싱글톤 리소스를 식별 할 수 있습니다.

3. URI

REST API는 URI를 사용해 리소스를 처리하기 때문에 리소스의 이름을 직관적이고 사용하기 쉽게 만들어야 사용하기 쉽습니다.

---

naming tip

1. 명사 사용

: 명사에는 동사에 없는 속성이 있는데, 리소스에도 속성이 있어 이를 표현하기에 명사가 좀 더 적합

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}

2. 일관성

• 슬래시(/)를 사용해 계층관계를 표현

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}

• URI에 마지막에 슬래시(/)사용 X -> 혼동을 줄 수 있음

👎http://api.example.com/device-management/managed-devices/
👍http://api.example.com/device-management/managed-devices

• 하이픈(-) 사용해 가독성 향상

👎http://api.example.com/device-management/managed-devices
👍http://api.example.com/devicemanagement/manageddevices

• 밑줄(_) 사용 X, 밑줄 대신 하이픈(-)사용

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

• URI에 소문자 사용

👍http://api.example.org/my-folder/my-doc
👎HTTP://API.EXAMPLE.ORG/my-folder/my-doc
👎http://api.example.org/My-Folder/my-doc

3. 파일 확장자 사용 X

파일 확장자는 Content-Type에 의존해 처리

👎http://api.example.com/device-management/managed-devices.xml
👍http://api.example.com/device-management/managed-devices

4. URI에 CRUD 사용 X

어떤 CRUD 기능을 하는지는 HTTP 요청 방법을 사용해 표현

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

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

5. 쿼리 구성요소를 사용해 URI 컬렉션 필터링

http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices?region=USA
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ&sort=installation-date