Eu quero apoiar a paginação na minha API RESTful.

Meu método de API deve retornar uma lista de produtos JSON por meio de/products/index. No entanto, existem potencialmente milhares de produtos, e eu quero paginá-los, então minha solicitação deve ser algo como isto:

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

Mas como minha resposta JSON precisa ser? Os consumidores da API normalmente esperariam metadados de paginação na resposta? Ou é apenas uma matriz de produtos necessária? Por quê?

Parece que a API do Twitter inclui metadados:https://dev.twitter.com/docs/api/1/get/lists/members (veja Exemplo de Pedido).

Com metadados:

{
  "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"
    }
  ]
}

Apenas uma matriz de produtos (sem metadados):

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