💡 REST Resource Naming Guide를 정리한 내용입니다
1. What is a Resource?
1.1 Singleton and Collection Resources
resource는 singleton이거나 collection이다.
예를 들어 “customers”은 collection resource이고, “customer”은 singleton resource이다.
“customers” collection resource는 URI로 “/customers”를 사용하고, singleton resource인 “customer”은 URI로 “/customers/{customerId}” 를 사용해 식별할 수 있다.
1.2 Collection and Sub-collection Resources
resource에는 하위 collection의 resource도 포함되어 있을 것이다.
“customer”의 하위 collection resource인 “acoounts”는 “/customers/{customerId}/accounts”를 URN으로 사용해 식별할 수 있다.
비슷하게, 하위 collection resource인 “accounts” 안에 있는 singleton resource “account”는 “/customers/{customerId}/accounts/{accountId}”를 사용해 식별할 수 있다.
2. Best Practices
2.1 Use nouns to represent resources
RESTful URI는 동사형 resource가 아닌 명사형 resource를 참조해야 한다.
명사에는 동사에는 없는 속성이 있기 때문이다. 마찬가지로, resource에도 속성이 있다.
resource의 몇 가지 예시:
- 시스템의 사용자 (Users of the system)
- 사용자 계정 (User Accounts)
- 네트워크 장치 (Network Devices)
위의 resource의 URI는 아래처럼 설계할 수 있다.
http://api.example.com/device-magagement/managed-devices
http://api.example.com/device-magagement/managed-devices/{device-id}
http://api.example.com/user-management/users
http://api.example.com/user-management/users/{id}더 명확하게 하기 위해서는, resource archetype를 네 가지 카테고리(document, collection, store, controller)로 분류하면 된다. 그 후, resource를 하나의 archetype에 넣고 앞으로 나온 naming 규칙을 사용하는 것이 가장 좋은 방법이다.
획일성을 위해, 둘 이상의 archetype이 혼합된 resource를 설계하는 것을 지양해야 한다.
2.1.1 document
document resource는 객체 인스턴스나 데이터베이스 레코드와 유사한 단일 개념이다.
REST에서는 document resource를 resource collection 안에 있는 단일 resource로 볼 수 있다. document의 상태 표현에는 값이 있는 필드와 다른 관련된 resource에 대한 링크가 모두 포함된다.
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/admin2.1.2 collection
Collection resource는 서버가 관리하는 resource의 directory이다.
Client는 collection에 추가할 새로운 resource를 제안할 수 있다. 하지만, 새 resource를 만들지 여부를 결정하는 것은 collection resource이다.
Collection resource는 포함하려는 resource를 선택하고 포함된 각 resource의 URI도 결정한다.
Collection resource의 archetype를 나타내기 위해서는 “복수” 이름을 사용하자.
http://api/example.com/device-management/managed-devices
http://api.example.com/user-management/users
http://api.example.com/user-management/users/{id}/accounts2.1.3 store
Store은 client가 관리하는 resource repository이다. store resource는 API client가 resource를 넣고, 다시 꺼내고, 삭제할 시기를 결정할 수 있다.
Store은 새로운 URI를 생성하지 않는 대신, 저장된 각 resource는 URI를 가진다. URI는 client가 resource를 처음 store할 때 결정한다.
Resource의 archetype를 나타내기 위해서는 “복수” 이름을 사용하자.
http://api.example.com/song-management/users/{id}/playlists2.1.4 controller
Controller resource는 절차적 개념을 모델링한다. controller resource는 매개변수가 있고 값, 입력값, 출력값을 반환하는 실행 가능한 함수와 같다.
Controller의 archetype를 나타내기 위해서는 “동사” 이름을 사용하자
http://api.example.com/cart-management/users/{id}/cart/checkout
http://api.example.com/song-management/users/{id}/playlist/play2.2 Consistency is the key
일관성 있는 resource 명명 규칙과 URI 형식을 사용하여 모호성을 최소화하고 가독성과 유지 관리 가능성을 최대화한다.
2.2.1 계층적 관계를 나타날 때는 ‘/’를 사용해라
‘/’ 문자는 resource 간의 계층적 관계를 나타내기 위해 URI의 경로 부분에 사용된다.
http://api.example.com/decive-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.2.2 URI 마지막에 ‘/’를 사용하지 마라
URI 경로 내의 마지막 문자로서 ‘/’는 의미 값을 추가하지 않으며 혼동을 줄 수 있으므로 URI에서 삭제하는 것이 좋다.
http://api.example.com/device-management/managed-devices/
http://api.example.com/device-management/managed-devices /*This is much better version*/2.2.3 URI 가독성 향상을 위해 하이픈(-)을 사용해라
URI를 쉽게 읽고 해석할 수 있도록 하이픈(-) 문자를 사용하여, 긴 경로 segment에서 이름의 가독성을 향상시켜라.
http://api.example.com/inventory-management/managed-entities/{id}/install-script-location //More readable
http://api.example.com/inventory-management/managedEntities/{id}/installScriptLocation //Less readable2.2.4 밑줄(_)를 사용하지 마라
구분 기호로 하이픈(-) 대신 밑줄(’_’)를 사용할 수 있다. 하지만, 응용 프로그램의 글꼴에 따라 밑줄(’_’) 문자가 일부 브라우저나 화면에서 부분적으로 가려지거나 보이지 않을 수 있다.
이런 혼동을 방지하기 위해 밑줄(’_’) 대신 하이픈(’-’)을 사용해라.
2.2.5 URI에서 소문자를 사용해라
URI 경로에서는 일관되게 소문자를 사용해야 한다.
http://api.example.org/my-folder/my-doc //1
HTTP://API.EXAMPLE.ORG/my-folder/my-doc //2
http://api.example.org/My-Folder/my-doc //3위의 예에서 1, 2번은 같은 URI이지만, 3번은 My-Folder를 첫 문자를 대문자로 사용하기 때문에 다른 URI이다.
2.3 Do not use file extensions
파일 확장자는 보기에 좋지 않으며, 사용한다고 해서 어떠한 이점도 없다. 파일 확장자를 제거하면 URI의 길이도 줄어드므로 사용할 이유가 없다.
위와 같은 이유로, 파일 확장자를 사용해 API의 미디어 유형을 강조한다면, 본문 내용을 어떻게 처리할지 결정하는 과정에서 Content-Type header를 통해 전달되는 미디어 유형에 의존하게 된다.
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*/2.4 Never use CRUD function names in URIs
CRUD 기능을 나타내기 위해 URI에 CRUD 함수 이름을 사용해서는 안된다. URI는 resource를 고유하게 식별하는 데만 사용되어야 하며, resource에 대한 조치를 식별하기 위해서 사용되면 안된다.
어떤 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}2.5 Use query componet to filter URI collection
종종 특정 resource 속성을 기반으로 resource collection을 정렬, 필터링 또는 제한해야하는 요구사항이 발생한다.
이런 요구사항의 경우 새 API를 생성하는 대신 resource collection API에서 정렬, 필터링 및 페이지 매김 기능을 활성화하고 입력 매개변수를 쿼리 매개변수로 전달하자.
댓글