I’m having trouble finding any information about this so I thought I’d ask the community here if there are any conventions on how to give the end user of a REST interface pagination info.
In particular I’m wondering should I return the total number of objects so they can calculate the number of pages, or the number of pages, or both? How should I return this information? I can see a few different ways it could work:
- Have a separate call to get the number of results. This would require multiple calls from the client so it doesn’t seem optimal.
- Return this information as headers in the response.
- Add this information to my root object.
I’m asking primarily so I can avoid catching people out by doing something completely different to any established conventions so I’d appreciate any comments on what is the best way, whether I’ve missed any obvious solutions, etc.
Thanks.
If you look here http://www.iana.org/assignments/link-relations/link-relations.xml there are standardized link relations for first, last, next and previous. You should embed links into the returned representation and identify those links using the standard link relations.
Your client code should be aware of those special link relation names and use the links as required. If the “next” link is not present in the response then your client should assume it is at the last page and if the “previous” link is not present, then you must be at the first page.
As far as returning the number of pages available, I am not aware of any standard, as that number is really only used for display purposes so it does not require special conventions.