Resource - Paging information

This page explains the common elements of resources that support paging. All those resources have common attributes and link rels.

Properties

A resource that supports paging contains the following properties:

Property	Description
paging	A property with the following sub properties: elements: number of items returned in this response offset: index of first returned item in the collection limit: maximum number of items requested by the caller totalElements: Total number of items in the folder (i.e. of all pages) after application of a filter, if any. The property is optional, but requestable. A client can force that the property is returned using the query parameter insist=totalElements.

Property

Description

paging

A property with the following sub properties:

elements: number of items returned in this response
offset: index of first returned item in the collection
limit: maximum number of items requested by the caller
totalElements: Total number of items in the folder (i.e. of all pages) after application of a filter, if any. The property is optional, but requestable. A client can force that the property is returned using the query parameter insist=totalElements.

Example:

{
  "paging": {
    "limit": 50,
    "offset": 0,
    "elements": 50,
    "totalElements": 167
  }
}

Links

A resource that supports paging has the following links:

Link rel	Verb	Description
self	GET	Returns the same page of the items in this collection.
next	GET	Returns the next page of items in this collection. The page size is equal to the value of "limit" in the paging property. The link is only present if there is a next page.
prev	GET	Returns the previous page of items in this collection. The page size is equal to the value of "limit" in the paging property. The link is only present if there is a previous page.
first	GET	Link that returns the first page of the collection, where limit is the page size.

Link rel

Verb

Description

self

GET

Returns the same page of the items in this collection.

GET

Returns the next page of items in this collection. The page size is equal to the value of "limit" in the paging property. The link is only present if there is a next page.

GET

Returns the previous page of items in this collection. The page size is equal to the value of "limit" in the paging property. The link is only present if there is a previous page.

first

GET

Link that returns the first page of the collection, where limit is the page size.

Additional links are possible.

Query parameters

A resource that supports paging supports the following query parameters:

Query parameter	Description
limit	Maximum number of items in the result. Note that the service may enforce a stricter limit to avoid performance issues. The next, prev, and first links will link to result pages with the same limit restriction to allow for an easy paging through the results. If a caller doesn’t request a limit or requests an invalid limit (e.g. a negative value), the CTC service will determine the number of items it returns.
offset	Request the list of items starting with the given offset (null-based).

Query parameter

Description

limit

Maximum number of items in the result. Note that the service may enforce a stricter limit to avoid performance issues.

The next, prev, and first links will link to result pages with the same limit restriction to allow for an easy paging through the results.

If a caller doesn’t request a limit or requests an invalid limit (e.g. a negative value), the CTC service will determine the number of items it returns.

offset

Request the list of items starting with the given offset (null-based).

Examples:

Query paramters	Description
<none>	Returns the first page of the results with a number of items defined by the service.
?offset=10	Skips the first 10 items (index 0 to 9) and returns the items starting with #10. The number of returned items is defined by the service.
?limit=5&offset=10	Skips the first 10 items (index 0 to 9) and returns 5 items, starting with #10. Note that the service may enforce a stricter limit to avoid performance issues.

Query paramters

Description

<none>

Returns the first page of the results with a number of items defined by the service.

?offset=10

Skips the first 10 items (index 0 to 9) and returns the items starting with #10. The number of returned items is defined by the service.

?limit=5&offset=10

Skips the first 10 items (index 0 to 9) and returns 5 items, starting with #10. Note that the service may enforce a stricter limit to avoid performance issues.