0

I have been working on an API and pagination is required. Only 25 elements will be returned in each request. I was looking around for standards and I seem to see 2 different things going on.

  1. The Link Header

Example:

Link: <https://api.github.com/user/repos?page=3&per_page=100>; rel="next",
  <https://api.github.com/user/repos?page=50&per_page=100>; rel="last"
  1. In the JSON response

Example:

"paging":  {
    "previous":  "http://api.example.com/foo?since=TIMESTAMP"
    "next":  "http://api.example.com/foo?since=TIMESTAMP2"
}

Question:

Should I do both? and that being said; is the key "paging" the correct key? or "links" or "pagination"

Community
  • 1
  • 1
KernelCurry
  • 1,297
  • 1
  • 13
  • 31
  • Are you building the API for you or someone else? If yourself, then the standards are all up to you. – Kai Qing Jun 26 '14 at 00:49
  • Will be a publicly accessible API http://mtgapi.com – KernelCurry Jun 26 '14 at 00:50
  • 1
    That doesn't answer the question. is it YOUR API or are you building it for a client? If you invent it and people can access it, they ar at your mercy. You can call "page" whatever you want and force them into an insane architecture they will despise you for. But if it is for a client, they may have expectations to adhere to first, which should be asked if you have doubts. Alternatively, you can just assume the whole world expects page=1&per_page=30 to be a perfectly suitable structure that is not confusing. Adding your own methods is perfectly ok. method=since&timestamp=xxx&per_page=30&page=2 – Kai Qing Jun 26 '14 at 01:05
  • So your answer is "there is not standard and i can do what ever I want" ? Thanks for the input. Going to hold off for a few more responses before I continue with development. – KernelCurry Jun 26 '14 at 02:21

1 Answers1

0

I would say it depends on the structure of data you return (and may return in the future).

If you never have nested objects that need their own links, then using the Link header is (mildly) preferable, because it's more correct. The issue with nested objects is that you can't nest Link headers.

Consider the following collection entity:

{
    "links": {
        "collection": "/cards?offset=0&limit=25"
    },
    "data": [
        {
            "cardName": "Island of Wak-Wak",
            "type": "Land",
            "links": {
                "set": "/cards?set=Arabian Knights"
            }
        },
        {
            "cardName": "Mana Drain",
            "type": "Interrupt",
            "links": {
                "set": "/cards?set=Legends"
            }
        }
    ]
}

There's no good way to include links for the cards in the headers.

Eric Stein
  • 13,209
  • 3
  • 37
  • 52