42

When implementing a Rest API, with parameters for paging, should paging be zero indexed or start at 1. The parameters would be Page, and PageSize.

For me, it makes sense to start at 1, since we are talking about pages

The Applicationist
  • 485
  • 1
  • 4
  • 12
  • 1
    So, use 1 and document it properly :) – cassiomolin Feb 23 '16 at 23:38
  • Well, Yes! It's one of those decision stages where I'd hate for people to be criticizing the decision for years to come! If of course its a case of some people prefer one way and some the other.. I'm happy to just pick something and go with it! – The Applicationist Feb 23 '16 at 23:41
  • 3
    There are hundreds of thousands of APIs using dozens of different approaches. Just pick approach that suits you better and, again, *document it properly*. Make an API you would love to use. – cassiomolin Feb 24 '16 at 00:04

2 Answers2

40

There's no standard for it. Just have a look around: there are hundreds of thousands of APIs using different approaches.

Most of APIs I know use one of the following approaches for pagination:

  • offset and limit or
  • page and size

Both can be 0 or 1 indexed. Which is better? That's up to you.

Just pick the one that fits your needs and document it properly.

Additionally, you could provide some links in the response payload to make the navigation easier between the pages.

Consider, for example, you are reading data from page 2. So, provide a link for the previous page (page 1) and for the next page (page 3):

{
    "data": [
        ...
    ],
    "paging": {
        "previous": "http://api.example.com/foo?page=1&size=10", 
        "next": "http://api.example.com/foo?page=3&size=10" 
    }
}

And remember, always make an API you would love to use.

cassiomolin
  • 124,154
  • 35
  • 280
  • 359
1

True, there's no standard for this.

I find that Microsoft based products used (old ones like DAO for Visual Basic 6, Visual C++ 6 and similar products) to start their pagination from 1, but a lot of other tech stacks uses 0. Gradually I find that more and more libraries are using 0 instead of 1.

Why is this? It's because, mathematically speaking, it's easier to map pageIndex starting from 0 to rowNumber in DB or Array. Suppose you have a dataset fetched from a Table in DB with 100 records. Now you want to send the second page (pageSize = 10 for example). With pageIndex starting from 0, then you only need to write

startRowNumber = pageIndex * pageSize;
return dataSet[startRowNumber, startRowNumber + pageSize]

Because in most DBs and languages, arrays/lists are 0-indexed. And even if your Rest API language uses a 1-indexed array, you would still have a problem when mapping a 1-indexed pageIndex to recordIds. For example: Suppose you have a dataset indexed 1..100 (not 0..99), and you want to send the 11th to 20th records, as the second page (here pageSize=10 and pageIndex=2, because in your case you start with 1). This means you need use the formula

((pageIndex - 1) * pageSize) + 1 ; // to get the number 11.

You see that it's easier to have a 0-indexed paging for developers.

1-indexed pagination makes more sense to human users, because we start with 1 when counting everything.

Nicholas Singgih
  • 11
  • 2