[REST API] REST에서의 리소스 이름 짓기

REST API를 설계하다보면 이름을 짓는게 어렵습니다. uri path를 사용해야할지.. body를 사용해야할지, 그리고 body를 사용한다면 json을 사용하는게 적합할까요? 아니면 query를 이용하는게 적합할까요? 오늘은 제 나름대로의 리소스의 이름을 짓는 가이드에 대해서 제가 찾아본 나름대로의 내용을 정리하여 설명드리도록 하겠습니다.

리소스 이름 가이드

이전 포스트에서 우리는 REST에서는 기본 데이터 표현을 리소스라고 하고 이러한 요소에는 Data, metadata, link가 있다는 것을 알게 되었습니다.

리소스의 이름의 중요성은 로이필딩의 논문에서도 아래와 같이 언급되고 있습니다.

The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. “today’s weather in Los Angeles”), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author’s hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.

Resource는 사용되어지며 여러가지의 형태를 띄게 됩니다.

• Resource는 단건일 수 있고, 단건의 집합일 수 있습니다.
  • customer라고 하면 1명의 고객이되며 이들의 집합은 customers는 손님 전체를 뜻
    • 손님들 : /customers
    • 2번ID를 가진 손님 : /customers/2
• Resource는 서브Resource를 포함할 수 있습니다.
  • 손님들의 계좌를 관리한다면, 손님의 하위에 계좌를 포함할 수 있습니다.
    • 2번 손님의 모든 계좌 : /customers/2/accounts
    • 2번 손님의 2번 계좌 : /cusotmers/2/accounts/2

REST API 설계시 이렇게 model을 만들어 놓고 이를 사용하는 Client에게 API를 공개합니다. 만약 Naming 설계가 잘 이루어져 있다면 Client가 사용하기 쉬울 것이며, 그렇지 않다면 사용하기 쉽지 않을수도 있습니다.

동사가 아닌 명사로 Resource를 표현하라

RESTful URI는 동사가 아니라 명사 구성하는 것을 추천합니다. 왜냐하면 명사는 해당 Resource의 속성을 표현할 수 있지만 동사는 그렇지 못하기때문입니다. 아래에 예를 URI로 표현해 보겠습니다.

• Users of the system 
• User Accounts
• Network Devices etc.

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}

좀 더 구체적으로 나누면 Resource의 표현방식은 document, collection, store 그리고 controller 4가지로 나눌수 있다고 합니다. 각 표현 방식에 대해서 한번 알아보도록 하겠습니다.

 

• document
  • document는 1개의 개체를 나타내는 것으로 객체 인스턴스, Datbase의 record와 유사한 개념을 가집니다. REST에서는 리소스 집합(collection)중 하나로 표현되어지며 일반적으로 collection의 뒤에 /를 통해 구분되어집니다.

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
  • collection은 단일 Resource(document)들의 묶음입니다. 사용자(Clients)들은 일반적으로 새로운 Resource를 추가할 때, 또는 단일 Resource가 아닌 다량의 Resource가 필요할 때 collection Resource를 호출합니다. 일반적으로 복수형태의 단어를 사용합니다.

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
  • store는 client입장의 resource저장소입니다. 장바구니 같은 개념이라고 생가하시면 좋을 것 같습니다. store URI는 API로 client가 resource를 넣고 빼고를 자유롭게 할 수 있게 합니다. 새로운 URI를 생성하지 않으며, 처음에 resource를 등록할 때 client가 전달한 key로 저장합니다. 복수의 형태를 사용합니다.

http://api.example.com/cart-management/users/{id}/carts
http://api.example.com/song-management/users/{id}/playlists

 

•  contoller
  • controller resource model은 절차적인 개념입니다. Controller Resource는 Client에서 Server의 function을 실행가능한다는 함수와 비슷하며, 파라미터와 리턴값이 있습니다. 본 문서에서는 controller의 경우 resource를 조작하는게 아닌 직접 function을 실행하는 것이기 때문에 이런 경우에는 동사를 사용해도 좋다고 합니다.

http://api.example.com/cart-management/users/{id}/cart/checkout
http://api.example.com/song-management/users/{id}/playlist/play

Consistency is the key

그외에 간단한 참고사항입니다.

1. 계층적 구조를 나타낼 때 /를 사용하라.
2. URI path의 제일 마지막에는 /를 사용하지 말라.
3. -를 이용하여 띄어쓰기를 대신하라. (cabab)
4. _를 사용하지 말라
5. 소문자를 사용하라.
6. file의 확장자를 사용하지 말라.

Query의 사용

API를 만들다보면 resource들을 정렬하고 필터하는 등의 조건이 필요할 수 있습니다. 이때는 query를 이용하는 것이 좋습니다.

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

Get에 대한 추가사항

Get을 통해 정보를 얻을 때 조건을 주고 싶을 때가 있습니다. 이때 생각할 수 있는것이 body에 정보를 주거나 url에 정보를 주는 방법입니다.

일반적으로 GET request를 할때는 url에 정보를 주라고 합니다. 왜냐하면 body에 정보를 넣으면 REST의 원칙인 cache하지 못하기 때문입니다. cache는 URL을 이용해서만 사용할 수 있다고 합니다. 그리고 bookmark도 불가능하다는 점에 따라서 GET request를 할때 url에 param으로 정보를 주라고 합니다.

아래를 참고하였습니다.

https://stackoverflow.com/questions/5020704/how-to-design-restful-search-filtering

마무리

이렇게 Resource의 이름을 짓는 방법에 대해서 오늘 알아보았습니다. 이렇게 가이드를 만들긴 했지만 상황에 따라서, 회사에 때라서 같은 function일지라도 내용이 많이 달라질 수 있을것같습니다. 어디까지나 참고를 하시고 본인의 상황에 맞게 적용하는것이 중요할 것 같습니다.

감사합니다.

다음시간에는 SOAP와 REST의 차이점에 대해서 한번 짚고 넘어가보도록 하겠습니다.

참조

https://restfulapi.net/resource-naming/