Pagination

Overview

SCALAR APIs support the following pagination scheme to ensure fast API performance and optimal data transfer when big set of records need to be returned. Each SCALAR API contract will clearly indicate which pagination methodology it uses.

Offset-based pagination

Offset-based pagination uses an offset and limit to run through the result set. An example query would look like GET /items?limit=20&offset=100, which returns 20 rows starting with the 100th row.

*Example:
(Assume the query is ordered by "created date" in a descending order )

First API call:

curl -X GET "https://asset-management.api.eu1.scalar.zf.com/v1/assets?limit=20&offset=0" -H "accept: application/json"

To access the next 20 items, you need to make the following request

curl -X GET "https://asset-management.api.eu1.scalar.zf.com/v1/assets?limit=20&offset=20" -H "accept: application/json"

And likewise for the 3rd set of items

curl -X GET "https://asset-management.api.eu1.scalar.zf.com/v1/assets?limit=20&offset=40" -H "accept: application/json"

*Sample Request and Response

GET https://asset-management.api.eu1.scalar.zf.com/v1/assets?limit=20&offset=40
 
200 OK
{
    "items": [
        {
            "assetId": "<uuid>",
            "vin": "...",
            ...
        },
        {
            ...
        },
        ...
    ],
    "metadata": {
    ...
        "pagination": {
            "offset":40,
            "limit": 20,
            "previousOffset": 20,
            "nextOffset": 60,
            "currentPage": 2,
            "pageCount": 40,
            "totalCount": 1000
        },
    ...
    }
}

Cursor-based pagination

Cursor-based pagination uses a cursor and limit to run through the result set. As opposed to offset-based pagination, cursors refers to a data element rather than a sequence number in the result set. We only support forward pagination, because this is most useful for syncing machine-to-machine information.

Example
(Assume the query is ordered by "created date" in ascending order)

First API call:

curl -X GET "https://trailer.api.eu1.scalar.zf.com/v1/alarms" -H "accept: application/json"

In the response you would get the next page cursor which can be used for the subsequent API call.

{
  "items": [
	{}...
  ],
  "metadata": {
    "pagination": {
      "nextCursor": "MTAxNTExOgdyugze15NDE"
    }
  }
}

The next API call should use the cursor obtained from the previous call.

curl -X GET "https://trailer.api.eu1.scalar.zf.com/v1/alarms?after=MTAxNTExOgdyugze15NDE" -H "accept: application/json"

On the last page the server returns an empty next cursor.

Caller could provide a limit (of pages) but if the request is more than the allowed page size than it would default to the maximum limit. e.g. max allowed page size is 25 and request is 50 → (min(25,50)=25) and also if the Limit is not provided it takes the maximum limit.

curl -X GET "https://trailer.api.eu1.scalar.zf.com/v1/alarms?limit=20" -H "accept: application/json"

Paging	Object
nextCursor	String

Please note that the createdSince and cursor should be used together in a request to move from page to page starting from the createdSince.

Request Params	Data Type	Request Description
createdSince	String	Return only new data using the created date time value from the last record in previous request.
after	String	Retrieve the next page for your current request using the nextCursor provided

Paging Object

syntax query: ?limit=25&after=MTAxNTExOgdyugze15NDE  --> next set
             
response:
  “metadata”: {
    “pagination”: {        
        "nextCursor”: “AX125dRthUIOGab5P”
       }
    }