RESTFul URI = scheme "://" authority "/" path [ "?" query ] [ "#" fragment ]
개요
사이드 프로젝트 중 '공고' 라는 리소스를 반환하는 api를 설계해야했다. 요청된 '년도'와 '월'에 속한 공고들을 리스트로 응답해야 했는데, year/month 를 'path'로 넣을지, 'query'로 넣을지 고민이 되었다.
/postings/year/{year}/month/{month}
path 에 year/month를 넣는건 안될 것 같았지만, 왜 안되는지 타당한 이유가 떠오르지 않아 지인이 추천해준 책의 도움을 받아 나름 고민해보았다. 책의 이름은 REST API Design Rulebook 이며, RESTFul 한 API 설계를 위한 Rule을 소개하고 있다.
REST API Design Rulebook
언급했다시피 RESTFul 한 API 설계를 위한 Rule을 소개하고 있는 책이다. 이 중 도움 받은 내용을 간략하게 정리해본다.
Resource Archetypes
URI 자체가 Uniform Resource Identifiers 의 약자인 만큼, Resource 는 REST API에서 굉장히 핵심적인 개념이된다. 본 책에선 Resource 를 세 가지 원형(Archetype)으로 분류하고 있다.
- Document: 객체 인스턴스 혹은 데이터베이스의 record 같은 단일 개념의 리소스.
- Collection: 리소스의 집합. 다만, 서버에서 관리되는 집합이므로 클라이언트에서 컬렉션에 새로운 리소스를 추가하려 제안해도 서버에서 최종 결정권을 가진다.
- Store: 리소스의 집합. 클라이언트에서 결정권을 가지므로 업데이트나 삭제 등의 작업이 클라이언트의 결정에 따른다.
- Controller: 인풋과 아웃풋이 있는 함수와 같은 리소스 개념. 보통 URI path의 마지막에 붙는다.
collection 과 store 가 헷갈릴 수 있는데, 다음 축구 리그와 관련된 예시를 보면 직관적으로 이해하는데 도움이 될 듯 하다.
- collection 예시:
http://api.soccer.restapi.org/leagues/seattle/teams- seattle 은 leagues에 속한다. 하지만 사용자가 이를 맘대로 바꿀 수 없다. 그냥 원래 그랬던 거니깐.
- leagues 는 collection resource 다.
- store 예시:
PUT /users/1234/favorites/alonso- user 1234 는 alonso를 자신의 favorites 에 포함시킨다
- favorites 은 store resource 다.
URI Path Design
uri path 를 정의하며 지켜야 하는 몇 가지 룰이 소개되어 있다. year, month를 path를 포함시키는게 타당한지 힌트를 얻을 수 있을 것 같다.
여러 Rule이 있었지만, 다음 Rule을 보고 year와 month 를 path에 포함시키면 안되겠다라고 생각했다.
- Rule: A singular noun should be used for document names
그래도 아쉬우니깐 다른 룰도 소개하겠다.
- Rule: A plural noun should be used for collection names
- Rule: A plural noun should be used for store names
- Rule: A verb or verb phrase should be used for controller names
- Rule: Variable path segments may be substituted with identity-based
values - Rule: CRUD function names should not be used in URIs
+ URI Query Design
The query component of a URI contains a set of parameters to be interpreted as a variation or derivative of the resource that is hierarchically identified by the path component.
이 대목에서 소개한 'qeury'에 대한 글이 내 판단을 도와줄 것이라 생각했다.
위 굵은 글씨가 나에겐 쿼리 파라미터는 리소스의 변형(variation) 혹은 파생(derivative)으로 해석되는 파라미터의 집합이다 라는 말로 해석됐는데, 이게 무슨 말인지 잘 모르겠다.
그래서 일단 판단의 근거에선 제외.
결론
year 는 path가 아니라 query에 넣어야겠다
URI Path Design 에서 소개한 Rule 을 다시 보자.
Rule: A singular noun should be used for document names
단수 명사는 document 리소스의 이름으로 사용되어야 한다. year는 단수 명사다. 그럼 year 는 document 를 나타내어야 한다. 하지만 document 는 서버에서 생성된 '객체' 나 db에 저장된 'record' 등의 단일한 개념을 나타내어야 한다. 내 생각으론 year 는 서버에서 관리되는 객체나 단일 데이터가 아니므로 document 라고 보기 힘들다.
그런데 사실 생각해보면 당연하다. 처음에 써놓은 path 를 보자.
/postings/year/{year}/month/{month}
year, month 가 document라고 해도, postings의 하위 리소스가 아님이 자명하다. 개개의 posting이 가지는 프로퍼티 중 하나일 순 있지만, postings 라고 묶일 수 있는 리소스가 될 수 없다는 의미이다.
따라서, 다음과 같이 query에 넣는 방법이 타당하다.
/postings?year=2022&month=12
