CODEWITHSUNDEEP
javaspringresthyperlinkhateoas
MaxExplode
MaxExplode

Reputation: 2007

What pagination method is better for rest api's (page, size) or (limit, offset)

I searched many stack overflow answers,articles and could't get an concrete idea about this and that is why i'm asking this question,

References : 10 Best Practices for Better RESTful API

I am just wondering what should we need to use when we do pagination in rest apis, In spring framework they are providing (page,size) by default to implement paging in apis and i think using (page, size) is more human readable and make sense rather than (limit, offset), Is there any reason why spring is providing (page,size) by default rather than limit,offset and many answers are to justify that (limit,offset) is better than (page,size).

https://somewhere.com/results?page=1&size=20

https://somewhere.com/results?limit=20&offset=0

Upvotes: 10

Views: 21201

Answers (5)

PA.
PA.

Reputation: 29339

Why don't provide both?

This is what I use.

And this is a sample (very simplified) express code to show that's actually very simple.

The user may choose the (easier to understand) page&size

GET example.com/api/v1/things?page=2&size=20

or the (more precise but slightly more techie) limit&offset

GET example.com/api/v1/things?limit=20&offset=20

router.get('/', async (req, res) => {
  ...
  const DEFAULT_PAGE_SIZE = 20;
  let { limit, offset, page, size } = req.query;
  if (page != null) { 
    limit = size ?? DEFAULT_PAGE_SIZE; 
    offset = (page - 1) * limit};  
  } 
  if (limit == null) {
    limit = DEFAULT_PAGE_SIZE;
  }
  if (offset == null) {
    offset = 0;
  }
  ...
  let rows = await db.getAllThings(limit, offset);
  res.json(rows);
});

Upvotes: 0

tiriana
tiriana

Reputation: 668

I think limit/size is better because it gives the client more options. They can request any set of results. The downside is that the client needs to calculate the offset.

The page/size is tempting, because it is more natural for ppl, and easier for clients to implement. And as long as you don't need to get 50 results, but omit the first 25 of them it is fine. But if you do - that's a bummer.

Upvotes: 1

LEMUEL ADANE
LEMUEL ADANE

Reputation: 8818

In Page/PageSize vs Offset/Limit, using Page/PageSize is simpler, because PageSize is the same for all Pages ; but using Offset/Limit gives you more precise data if you are targeting specific range of items, and you cannot do this using Page/PageSize method. Image below shows you the relationship between the two:

enter image description here

On the first block if you are targeting for the item 6 to item 8, your PageSize is 3:

Limit = PageSize = 3
Page = 3 // from the first block above, item 6 to item 8 sits on Page 3
Offset = (Page * PageSize) - PageSize
Offset = (3 * 3) - 3
Offset = 6

On the second block if you are targeting for the item 7 to item 9, so your PageSize is 3 again:

Limit = PageSize = 3
Page = 3.3333 // from the 2nd block, item 7 to item 9 sits exactly in Page = 3.3333, and not in Page = 3
Offset = (Page * PageSize) - PageSize
Offset = (3.3333 * 3) - 3
Offset = 9.9999 - 3
Offset = 7

On the 3rd block you are targeting for item 7 to item 10, so your PageSize = 4:

Limit = PageSize = 4
Page = 2.75 // from the 3rd block, item 7 to item 9 sits exactly in Page = 2.75, and not in Page 3, if the PageSize is 4
Offset = (Page * PageSize) - PageSize
Offset = (2.75 * 4) - 4
Offset = 11 - 4
Offset = 7

Ovbiously the Offset is the starting index of your target items and the Limit is the count of the items you are targeting. I'm just showing you the relationship of the 2 methods.

Upvotes: 11

admly
admly

Reputation: 317

I use the page&limit approach. IMHO those are the best names for params. So it would go like this:

https://somewhere.com/results?page=1&limit=10

I couldn't find any clear answers on 'how to do it' question.

Upvotes: 1

CodeFox
CodeFox

Reputation: 447

Limit and offset are a little easier to use in code if you don't use spring for example, you can pass these values directly to the dbms.

In case of page and size you have to calculate the values offset and limit. In case of a framework it will do the work for you.

But in my opinion, there is no "best way" of doing it. Both solutions works fine for multiple cases.

Upvotes: 4

Related Questions