Chcę obsługiwać paginację w moim RESTful API.

Moja metoda API powinna zwrócić listę produktów JSON za pośrednictwem/products/index. Istnieją jednak potencjalnie tysiące produktów i chcę je przejrzeć, więc moja prośba powinna wyglądać mniej więcej tak:

/products/index?page_number=5&page_size=20

Ale jak ma wyglądać moja odpowiedź JSON? Czy konsumenci API zazwyczaj oczekują w odpowiedzi metadanych paginacji? Czy potrzebny jest tylko szereg produktów? Czemu?

Wygląda na to, że API Twittera zawiera metadane:https://dev.twitter.com/docs/api/1/get/lists/members (patrz Przykładowy wniosek).

Z metadanymi:

{
  "page_number": 5,
  "page_size": 20,
  "total_record_count": 521,
  "records": [
    {
      "id": 1,
      "name": "Widget #1"
    },
    {
      "id": 2,
      "name": "Widget #2"
    },
    {
      "id": 3,
      "name": "Widget #3"
    }
  ]
}

Tylko szereg produktów (bez metadanych):

[
  {
    "id": 1,
    "name": "Widget #1"
  },
  {
    "id": 2,
    "name": "Widget #2"
  },
  {
    "id": 3,
    "name": "Widget #3"
  }
]