168
edits
Pagination: Difference between revisions
Jump to navigation
Jump to search
no edit summary
(Created page with "When APIs need to return a lot of data or if computing which items to show is expensive it is useful to return data in a page-wise fashion. If the response size is less than...") |
No edit summary |
||
| (2 intermediate revisions by the same user not shown) | |||
| Line 4: | Line 4: | ||
== API Structure == | == API Structure == | ||
A paginated resource starts at the first page: | A paginated resource starts at the first page: <code>/list</code>. The server can use any [[Media-Types | Media-Type]] it wants as long as the corresponding [[Media-Type specification | documentation]] indicates that the client should expect the pagination headers. | ||
If all the responses fit on one page, nothing needs to be done, and no additional headers need to be added. | If all the responses fit on one page, nothing needs to be done, and no additional headers need to be added. | ||
If there is more data than fits on the first page, the [[URL]] for the next page should be set using a [[Link Header]] with | If there is more data than fits on the first page, the [[URL]] for the next page should be set using a [[Link Header]] with <code>rel=next</code>. | ||
For subsequent pages, if the resource supports iterating backwards, a | For subsequent pages, if the resource supports iterating backwards, a Link Header with <code>rel=prev</code> should be added as well. | ||
If you want to support going to the first and last pages, those can be indicated with | If you want to support going to the first and last pages, those can be indicated with <code>rel=first</code> and <code>rel=last</code>. | ||
== | == Cursor Based Pagination == | ||
In order to allow [[HTTP Caching]] to do its work it is generally advised to use a reference to the first item on that page instead of a numeric page number. This prevents items falling between pages or being shown twice if items are being added / removed from the list while someone is browsing. An example is: | In order to allow [[HTTP Caching]] to do its work it is generally advised to use a reference to the first item on that page instead of a numeric page number. This prevents items falling between pages or being shown twice if items are being added / removed from the list while someone is browsing. An example is: <code>/list?startat=<item_id></code>. | ||
A fast way to do this is by fetching one item more than you want to return | A fast way to do this is by fetching one item more than you want to return and using the id of that element to construct the [[URL]] for the next page. | ||
[[Category: Terminology]] | |||