Pagination - Revision history

Thexa4 at 02:15, 19 January 2021

2021-01-19T02:15:03Z

← Older revision		Revision as of 19:15, 18 January 2021
Line 4:		Line 4:

	== API Structure ==		== API Structure ==
	A paginated resource starts at the first page: `/list`. 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.		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 `rel=next`.		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 Link Header with `rel=prev` should be added as well.		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 `rel=first` and `rel=last`.		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 ==		== 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: `/list?startat=<item_id>`.		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 and using the id of that element to construct the [[URL]] for the next page.		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]]

Thexa4 at 00:26, 19 January 2021

2021-01-19T00:26:47Z

← Older revision		Revision as of 17:26, 18 January 2021
Line 14:		Line 14:
	If you want to support going to the first and last pages, those can be indicated with `rel=first` and `rel=last`.		If you want to support going to the first and last pages, those can be indicated with `rel=first` and `rel=last`.

	== ~~Internal Implementation~~ ==		== 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: `/list?startat=<item_id>`.		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: `/list?startat=<item_id>`.

	A fast way to do this is by fetching one item more than you want to return ~~in the result~~ and using the id of that element to construct the ~~url~~ for the next page.		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.

Thexa4 at 16:21, 14 January 2021

2021-01-14T16:21:57Z

← Older revision		Revision as of 09:21, 14 January 2021
Line 10:		Line 10:
	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 `rel=next`.		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 `rel=next`.

	For subsequent pages, if the resource supports iterating backwards, a [[Link Header]] with `rel=prev` should be added as well.		For subsequent pages, if the resource supports iterating backwards, a Link Header with `rel=prev` should be added as well.

	If you want to support going to the first and last pages, those can be indicated with `rel=first` and `rel=last`.		If you want to support going to the first and last pages, those can be indicated with `rel=first` and `rel=last`.

Thexa4: 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..."

2021-01-14T16:21:36Z

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..."

New page

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 50kb you probably do not want to implement pagination yet. Given that a HTTP request is generally between 1 and 8kB doing pagination below that will generally make things worse.

== API Structure ==
A paginated resource starts at the first page: `/list`. 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 there is more data than fits on the first page, the [[URL]] for the next page should be set using a [[Link Header]] with `rel=next`.

For subsequent pages, if the resource supports iterating backwards, a [[Link Header]] with `rel=prev` should be added as well.

If you want to support going to the first and last pages, those can be indicated with `rel=first` and `rel=last`.

== Internal Implementation ==
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: `/list?startat=<item_id>`.

A fast way to do this is by fetching one item more than you want to return in the result and using the id of that element to construct the url for the next page.