API Pagination Standards - api

Question

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.
The Link Header
Link: https://www.rfc-editor.org/rfc/rfc5988
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"
In the JSON response
Link: API pagination best practices
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"

Answer 1

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.