improve wording

[ci skip]
pull/2164/head
Jan Sandbrink 10 years ago
parent 3bfcdcd3a9
commit ef222622ce
  1. 22
      doc/apiv3-documentation.apib

@ -221,9 +221,12 @@ There are two ways to access the result pages of a paginated collection:
* offset based pagination * offset based pagination
* cursor based pagination * cursor based pagination
The available ways of pagination depend on the collection queried. Some collection feature no pagination at all, meaning they
will always return all elements. Others might only offer one of the two pagination methods or both of them.
## Offset based pagination [/example/collection{?offset,pageSize}] ## Offset based pagination [/example/collection{?offset,pageSize}]
Offset based iteration works by specifying two values: the **offset** and the **pageSize**. The offset determines how many elements are Offset based pagination works by specifying two values: the **offset** and the **pageSize**. The offset determines how many elements are
skipped before the first element that is present in the result. The page size determines how many items there will be in the result. Note skipped before the first element that is present in the result. The page size determines how many items there will be in the result. Note
that the server might not allow arbitrarily large page sizes, a client should therefore always check the page size accepted by the server that the server might not allow arbitrarily large page sizes, a client should therefore always check the page size accepted by the server
using the **pageSize** property of the response. using the **pageSize** property of the response.
@ -232,6 +235,9 @@ The benefit of offset based pagination is that the total number of pages can be
to arbitrary pages within the collection. Offset based pagination is therefore well suited when a result is displayed to the end user to arbitrary pages within the collection. Offset based pagination is therefore well suited when a result is displayed to the end user
in the form of multiple pages anyway. in the form of multiple pages anyway.
A drawback of offset based pagination comes with concurrent modification of the collection. If the collection is modified
between two page requests, it is possible that the client receives elements close to the page boundaries twice or does not see them at all.
## view offset based [GET] ## view offset based [GET]
+ Parameters + Parameters
@ -272,15 +278,13 @@ in the form of multiple pages anyway.
## Cursor based pagination [/example/collection{?before,after,pageSize}] ## Cursor based pagination [/example/collection{?before,after,pageSize}]
A drawback of offset based pagination comes with concurrent modification of the result, as this can lead to the client receiving an element Cursor based pagination is intended to be used, when the client needs a consistent and complete (sub-) range of the collection,
twice or missing it altogether. e.g. in infinite scrolling scenarios. In cursor based pagination the client will receive a link to the next and
TODO: probably include a picture to illustrate the case (Twitter does so in its API-Docs: https://dev.twitter.com/rest/public/timelines)
Cursor based pagination is intended to be used, when the client needs a consistent and complete range of the collection, e.g. when it either
needs the complete collection or in infinite scrolling scenarios. In cursor based pagination the client will receive a link to the next and
the previous page in the result set. The guarantee is, that the boundaries of that page will align with the boundaries of the current page, the previous page in the result set. The guarantee is, that the boundaries of that page will align with the boundaries of the current page,
there are no omissions and no duplicates. However it is not immediately determinable how many "next" and how many "previous" pages there are. regardless of changes to the collection.
The drawback for cursor based pagination is, that it is not immediately determinable how many "next" and how many "previous" pages there are.
Cursor based pagination is therefore less suited for use cases where you want to directly "jump" to an arbitrary page.
## view cursor based [GET] ## view cursor based [GET]

Loading…
Cancel
Save