Paginating

Pagination is the placement of a limit on the number of records returned by an operation, often for performance reasons. The limit is called the page size. In the Connect REST API, the default page size is 1000 records.

In the November 2015 release and later, you can change the number of records displayed and the record with which to start displaying results. You use the following query parameters for pagination:

This topic contains the following sections:

Using Query Parameters for Pagination

You use the following query parameters for pagination:

  • limit. Sets the page size.
  • offset. Determines the record number from which to start retrieval.
  • totalResults. Displays the total number of results.

Note:

Only collection resources, such as incidents and contacts, support pagination. The maximum page size is 20,000 records.
When you set a page size, the collection response includes the following:
  • hasMore. Tells you whether there are any more records to display.
  • prev and next links. Enables you to navigate to the previous or next set of results if they exist.

Note:

Oracle recommends using the prev and next links, rather than the offset parameter, to navigate. The offset parameter affects performance significantly.

Using Pagination with Collection Resources

You use the GET method with the following syntax to use pagination with collection resources:

https://your_site_interface/services/rest/connect/version/
resource?limit=number_of_records[&totalResults=true]

For example, the following GET request:

https://mysite.example.com/services/rest/connect/v1.4/contacts?limit=20&totalResults=true

returns the first 20 contacts. The total number of contacts, the fact that there are more contacts that can be retrieved, and a next link (but not prev) are also shown:

{
    "items": [
    {
        "id": 2,
        "lookupName": "Susan Meadows",
        "createdTime": "2013-08-21T20:30:18Z",
        "updatedTime": "2013-08-21T21:02:09Z",
        "links": [
            {
            "rel": "canonical",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/contacts/2"
            }
        ]
    },
    {
        "id": 3,
        "lookupName": "George Langston",
        "createdTime": "2013-08-21T20:31:10Z",
        "updatedTime": "2013-08-21T21:04:22Z",
        "links": [
            {
            "rel": "canonical",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/contacts/3"
            }
        ]
    },
    ...
    {
        "id": 21,
        "lookupName": "Benjamin Washington",
        "createdTime": "2013-08-21T20:42:46Z",
        "updatedTime": "2013-08-21T20:42:46Z",
        "links": [
            {
            "rel": "canonical",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/contacts/21"
            }
        ]
    }
    ],
    "totalResults": 77,
    "hasMore": true,
    "links": [
        {
        "rel": "canonical",
        "href": "https://mysite.example.com/services/rest/connect/v1.4/contacts"
        },
        {
        "rel": "describedby",
        "href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/contacts",
        "mediaType": "application/schema+json"
        },
        {
        "rel": "next",
        "href": "https://mysite.example.com/services/rest/connect/v1.4/contacts?totalResults=true&limit=20&fromId=21"
        },
        {
        "rel": "self",
        "href": "https://mysite.example.com/services/rest/connect/v1.4/contacts?limit=20&totalResults=true"
        }
    ]
}

Combining Pagination with Other Query Parameters

You can combine pagination with other query parameters, such as q and fields, to refine your results. For example, these GET method requests are valid:

  • https://mysite.example.com/services/rest/connect/v1.4/incidents
    ?fields=subject,severity&limit=20&totalResults=true
  • https://mysite.example.com/services/rest/connect/v1.4/incidents
    ?q=createdTime>'2015-11-05T15:59:00Z'&limit=20&totalResults=true

Using Pagination with ROQL Tabular Queries

You can use pagination with ROQL tabular queries to refine your results, by using the limit parameter as part of the query. For more information, see Using ROQL Tabular Queries.

  1. Use the following GET request to return the first 50 rows from the contacts table:

    https://mysite.example.com/services/rest/connect/v1.4/
    queryResults?query=select * from contacts limit 50
    
  2. Use this GET request to get the next 50 contacts:

    https://mysite.example.com/services/rest/connect/v1.4/
    queryResults?query=select * from contacts where ID>50 limit 50
    
  3. Repeat the process by incrementing the where ID> integer expression by 50 (100, 150, and so on).