[rest] 객체의 총 항목 수를 반환하는 가장 좋은 RESTful 방법은 무엇입니까?

_{나는 최근에 이것과 다른 REST 페이징 관련 질문에 대한 광범위한 연구를 해 왔으며 여기에 내 발견 사항을 추가하는 것이 건설적인 것이라고 생각했습니다. 나는 페이징에 대한 생각과 그들이 친밀하게 관련된 수를 포함하도록 질문을 조금 확장하고 있습니다.}

헤더

페이징 메타 데이터는 응답 헤더 형식으로 응답에 포함됩니다. 이 접근 방식의 가장 큰 장점은 응답 페이로드 자체가 실제 데이터 요청자가 요청한 것입니다. 페이징 정보에 관심이없는 클라이언트의 응답 처리를보다 쉽게 ​​만듭니다.

총 수를 포함하여 페이징 관련 정보를 반환하기 위해 와일드에 사용되는 많은 (표준 및 사용자 정의) 헤더가 있습니다.

X-Total-Count

X-Total-Count: 234

이것은 내가 야생에서 찾은 일부 API 에서 사용됩니다 . 루프백에이 헤더에 대한 지원을 추가하기위한 NPM 패키지 도 있습니다 . 일부 기사 에서는이 헤더를 설정하는 것이 좋습니다.

Link헤더 와 함께 사용되는 경우가 많습니다. 페이징에는 매우 적합한 솔루션이지만 총 개수 정보가 없습니다.

링크

Link: </TheBook/chapter2>;
      rel="previous"; title*=UTF-8'de'letztes%20Kapitel,
      </TheBook/chapter4>;
      rel="next"; title*=UTF-8'de'n%c3%a4chstes%20Kapitel

나는 일반적인 합의가 사용하는 것으로,이 주제에 많이 읽고, 느낌이 Link헤더를 사용하여 클라이언트에 대한 링크를 페이징 제공하기 위해 rel=next, rel=previous이에 등의 문제는 인, 얼마나 많은 총 레코드의 정보 부족이다 많은 API가 이것을X-Total-Count 헤더 .

또는 JsonApi 표준 과 같은 일부 API 는 Link형식을 사용 하지만 헤더 대신 응답 엔벨로프에 정보를 추가하십시오. 이는 엔벨로프를 추가하여 실제 데이터 자체에 대한 액세스 복잡성을 증가시키는 대신에 메타 데이터에 대한 액세스를 단순화하고 총 수 정보를 추가 할 수있는 장소를 만듭니다.

컨텐츠 범위

Content-Range: items 0-49/234

Range header 라는 블로그 기사에서 홍보 한 결과, 페이지 매김을 선택합니다. . 저자는 페이지 매김에 Range및 Content-Range헤더를 사용하는 강력한 사례를 만듭니다 . 이 헤더 에서 RFC 를 주의 깊게 읽으면 실제로 RFC에서 바이트 범위를 넘어 그 의미를 확장하는 것이 예상되었으며 명시 적으로 허용되는 것을 알 수 있습니다. 의 맥락에서 사용하는 경우 items대신 bytes, 레인지 헤더는 실제로 모두 요청에 우리에게 항목의 특정 범위를 방법을 제공하고 응답 항목과 관련된 전체 결과의 범위는 무엇을 나타냅니다. 이 헤더는 또한 총 수를 표시하는 좋은 방법을 제공합니다. 그리고 일대일로 페이징을 매핑하는 것은 진정한 표준입니다. 또한 야생 에서도 사용됩니다 .

봉투

자주 사용 하는 Q & A 웹 사이트의 API를 포함 하여 많은 API 는 데이터에 대한 메타 정보를 추가하는 데 사용되는 데이터 래퍼 인 envelope를 사용합니다 . 또한 OData 및 JsonApi 표준은 모두 응답 범위를 사용합니다.

이에 대한 가장 큰 단점은 실제 데이터가 엔벨로프에서 찾아야하므로 응답 데이터 처리가 더 복잡해진다는 것입니다. 또한 해당 봉투에는 여러 가지 형식이 있으므로 올바른 것을 사용해야합니다. OData와 JsonApi의 응답 엔벨로프는 응답의 여러 지점에서 메타 데이터에서 혼합되는 OData와는 크게 다릅니다.

별도의 엔드 포인트

나는 이것이 다른 답변에서 충분히 다루어 졌다고 생각합니다. 여러 유형의 엔드 포인트가 있으므로 혼동된다는 의견에 동의하기 때문에 이것을 많이 조사하지 않았습니다. 모든 엔드 포인트가 (자원 모음)을 나타내는 것이 가장 좋다고 생각합니다.

추가 생각

응답과 관련된 페이징 메타 정보를 전달할 필요가있을뿐만 아니라 클라이언트가 특정 페이지 / 범위를 요청할 수도 있습니다. 일관된 솔루션으로 끝나기 위해이 측면을 보는 것도 흥미 롭습니다. 여기에서도 헤더 ( Range헤더가 매우 적합 함) 또는 쿼리 매개 변수와 같은 다른 메커니즘을 사용할 수 있습니다 . 어떤 사람들은 몇 가지 사용 사례에 의미가 있습니다 별도의 자원 (예를 들어 같은 결과 페이지를 치료 옹호 /books/231/pages/52나는 등 자주 사용하는 요청 매개 변수의 야생 범위를 선택 끝났다. pagesize, page[size]및 limit등 지원 외에 Range헤더 (요청 매개 변수로 게다가).

답변

/api/members?metaonly=true
/api/members?includeitems=0

HTTP/1.1 200

Pagination-Count: 100
Pagination-Page: 5
Pagination-Limit: 20
Content-Type: application/json

[
  {
    "id": 10,
    "name": "shirt",
    "color": "red",
    "price": "$23"
  },
  {
    "id": 11,
    "name": "shirt",
    "color": "blue",
    "price": "$25"
  }
]

206 Partial Content
Accept-Ranges: members
Content-Range: members 0-20/100

200 OK
Accept-Ranges: members
Content-Range: members 0-20/20