자원을 명사로 나타내라.
RESTful URI가 가리키는 자원은 객체이다. 그렇기 때문에 동사가 아니라 명사로 칭한다. 자원은 4가지 범주로 분류할 수 있다. 문서, 컬렉션, 스토어, 컨트롤 자원이 어떤 범주에 속하는지에 따라 일관된 네이밍을 사용한다.
- 문서
문서 자원은 DB의 하나의 레코드, 하나의 객체 인스턴스와 유사한 단일 자원의 개념이다. 단수를 사용하여 문서 자원을 표현한다.
- <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>
- 컬렉션
서버가 관리하는 리소스 디렉터리이다. 클라이언트에 의해 새로운 리소스 추가가 요청될 수 있다. (POST 사용) 복수를 사용하여 컬렉션 자원을 표현한다.
<http://api.example.com/device-management/managed-devices>
<http://api.example.com/user-management/users>
<http://api.example.com/user-management/users/{id}/accounts>
- 스토어
스토어는 클라이언트가 관리하는 자원 저장소이다. 클라이언트는 API를 이용하여 자원을 넣거나 가져올 수 있고 삭제할 수 있다. 복수를 사용하여 스토어를 표현한다.
<http://api.example.com/song-management/users/{id}/playlists>
- 컨트롤러
컨트롤러 자원은 인자와 반환 값, 인력 및 출력이 있는 실행 가능한 함수와 같다. 문서,컬렉션,스토어로 해결이 어려운 절차적 실행을 수행하기 위한 모델이다. 특정 자원을 가리키는 것이 아니라 실행인 만큼 예외적으로 동사를 사용한다.
<http://api.example.com/cart-management/users/{id}/cart/checkout>
<http://api.example.com/song-management/users/{id}/playlist/play>
‘-’하이픈을 사용하여 가독성을 높인다.
긴 경로 이름에 하이픈을 사용하여 가독성을 높혀라.
CRUD 함수 명을 사용하지 않는다.
URI는 자원을 가리키는 것이다. 어떤 동작을 가리켜서는 안된다.
HTTP GET <http://api.example.com/device-management/managed-devices> //모든 디바이스를 요청
HTTP POST <http://api.example.com/device-management/managed-devices> //새로운 디바이스를 생성
HTTP GET <http://api.example.com/device-management/managed-devices/{id}> //ID를 이용하여 디바이스를 요청
HTTP PUT <http://api.example.com/device-management/managed-devices/{id}> //ID를 이용하여 디바이스를 갱신
HTTP DELETE <http://api.example.com/device-management/managed-devices/{id}> //ID를 이용하여 디바이스 삭제
자원의 필터링을 위해서는 쿼리 파라미터를 사용한다.
자원을 정렬, 필터링 하거나 제한된 수량을 요청해야 할 때가 있다. 이때 쿼리 파라미터를 활용 한다.
<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>
https://seungwoo0429.tistory.com/37
https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation