title: Pagination response payload from a RESTful API
body: <p>I want to support pagination in my RESTful API.</p>
  
  <p>My API method should return a JSON list of product via <code>/products/index</code>. However, there are potentially thousands of products, and I want to page through them, so my request should look something like this:</p>
  
  <pre><code>/products/index?page_number=5&amp;page_size=20
  </code></pre>
  
  <p>But what does my JSON response need to look like? Would API consumers typically expect pagination meta data in the response? Or is only an array of products necessary? Why?</p>
  
  <p>It looks like Twitter's API includes meta data: <a href="https://dev.twitter.com/docs/api/1/get/lists/members" rel="noreferrer">https://dev.twitter.com/docs/api/1/get/lists/members</a> (see Example Request).</p>
  
  <p>With meta data:</p>
  
  <pre><code>{
    "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"
      }
    ]
  }
  </code></pre>
  
  <p>Just an array of products (no meta data):</p>
  
  <pre><code>[
    {
      "id": 1,
      "name": "Widget #1"
    },
    {
      "id": 2,
      "name": "Widget #2"
    },
    {
      "id": 3,
      "name": "Widget #3"
    }
  ]
  </code></pre>