REST 모범 사례 : 저장소가 메타 데이터를 반환해야합니까?

Question

나는 개인 프로젝트를 위해 내 첫 번째 REST API를 구축하고있다.

이 프로젝트에는 team에있을 수있는 player이라는 리소스가 있습니다. REST API design rulebook에 따르면 리소스는 문서또는저장소 중 하나 여야하며 가능한 한 이러한 역할을 분리해야합니다.

team과 같이 team 리소스에 메타 데이터를 추가하고 싶습니다. GET /teams/atlanta에 문서과 함께 player의 목록과 함께이 메타 데이터를 반환하면됩니다 ().

이것은 좋은 아이디어입니까? 그렇다면 왜? 왜 안되면 어떻게 해결할 수 있을까요?

나는 REST API를 개발하는 데 규칙이 없다는 것을 알고 있지만, 우수 사례가 있으며이를 준수하고 싶습니다. 또한 이것이 정말로 있으면 내 첫 번째 REST API라는 것을 잊지 마시기 바랍니다.

Answer 1

GET /teams/atlanta은 언급 한 창립 날짜와 같은 팀 정보만을 반환하고 GET /teams/atlanta/players은 해당 팀의 선수 목록을 반환하는 것이 좋습니다. 이러한 구분은 GET 이외의 HTTP 메소드를 사용하는 API를 제공 할 때 더욱 중요 해집니다.

예를 들어 팀에 플레이어를 추가하려는 경우 플레이어 개체를 /teams/atlanta/players으로 POST 할 수 있다면 원하는 때마다 전체 팀 개체를 /teams/atlanta 개로 푸시해야하는 경우보다 훨씬 쉬울 것입니다. 개별 플레이어 한 명을 추가 할 수 있습니다.

API가 데이터 검색 만 허용하는 경우 특정 클라이언트 응용 프로그램 용인 경우 모든 팀 데이터를 하나의 개체에 결합하여 클라이언트가 데이터를 추가로 요청하지 않아도되도록 저장하는 인수가 있지만 덜 유연하다는 것을 명심하십시오.

귀하의 응용 프로그램은 GET /teams으로 전화하여 팀 목록을 표시하려고 할 수 있지만 목록에있는 각 개체에 포함 된 모든 플레이어 정보가 상당히 많은 데이터이기 때문에 원하지 않을 것입니다. 그러나 GET /teams/atlanta이 플레이어를 반환하면 정보가 있으면 목록 버전에도 포함되지 않도록 일관성이 없습니다.

개인적으로 제가 제안한 것처럼 리소스를 분할하고 클라이언트가 추가 요청을해야 할지도 모른다는 사실을 알고 있습니다.