왜 알아보았는가
Restful API의 URI를 설계하면서 일관성있고 식별하기 좋은 방식을 고민했습니다.
팀 내에서 URI 컨벤션을 만들지 않고, 범용적으로 사용되는 Naming의 기준이 존재하는지 찾아보다 공식문서에 있는 Naming Guide를 발견해 아래와 같이 정리했습니다.
개념
자원 (resource)
In REST, the primary data representation is called resource
- 데이터의 주체가 되는 대상
- 행위가 아닌 대상 그 자체를 지칭
<Example>
- members
- boards
- items
문서 (document)
A document resource is a singular concept that is akin to an object instance or database record.
- 단일 개념 하나 (파일 하나, 객체 인스턴스, 데이터베이스 row)
<Example>
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)
A collection resource is a server-managed directory of resources.
- 서버가 관리하는 리소스 디렉터리
- 서버가 리소스의 URI를 생성
<Example>
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)
A store is a client-managed resource repository.
- 클라이언트가 관리하는 자원 저장소
- 클라이언트가 리소스의 URI를 알고 관리
<Example>
http://api.example.com/files
컨트롤러 (controller)
A controller resource models a procedural concept. Controller resources are like executable functions
- 문서, 컬렉션, 스토어로 해결하기 어려울 때 사용
- 동사를 직접 사용
- Controll URI라고 부름
<Example>
http://api.example.com/cart-management/users/{id}/cart/checkout
http://api.example.com/song-management/users/{id}/playlist/play
Best Practices
1. Use the “plural” name to denote the collection resource archetype.
“plural”은 단수보다 많은 양, 즉 복수를 나타내는 개념입니다. 공식문서는 다음과 같이 설계하는 것을 권장합니다.
http://api.example.com/users/{id}
2. 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}
3. Do not use trailing forward slash (/) in URIs
URI의 맨 뒤에 슬래쉬 “/”를 붙이는 것을 권장하지 않습니다.
<not recommended>
http://api.example.com/device-management/managed-devices/<recommended>
http://api.example.com/device-management/managed-devices
4. Use hyphens (-) to improve the readability of URIs
readability를 위해 필요한 경우 하이푼 “-” 사용을 권장합니다.
또한 언더바 “_”는 application의 font에 따라 인식되지 않을 수 있어 권장하지 않습니다. (직접 겪은 사례 참고!)
<not recommended>
http://api.example.com/devicemanagement/manageddevices<recommended>
http://api.example.com/device-management/managed-devices
5. Use lowercase letters in URIs
일관성 있도록 오직 소문자만 사용하는 것을 권장합니다.
<not recommended>
HTTP://API.EXAMPLE.ORG/my-folder/my-doc
http://api.example.org/My-Folder/my-doc<recommended>
http://api.example.org/my-folder/my-doc
6. Use query component to filter URI collection
정렬이나 필터링이 필요한 경우는 별도의 API로 분리하지 않고 query string을 활용하길 권장합니다.
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
