The pagination query parameters

Some endpoints return collections. However, the entire collection is typically not returned in a single call. Instead, only the first N resources are returned in the first payload. Each set of N resources is called a page. A caller can use "previous" and "next" links to access the previous or next page of N resources. The practice of separating a list of resources into pages is referred to as pagination.

Every endpoint that returns a collection has default pagination behaviors. Each payload contains one page of resources. There are several query parameters that refine these behaviors. This includes:

  • pageSize - limits the number of resources returned per page
  • pageOffset - specifies which page of resources to return
  • includeTotal - ensures the response includes a count of the entire number of resources that meet the request's criteria

pageSize limits the number of resources per page

For endpoints that return collections, you can use the pageSize parameter to limit the number of resources in each page. This can be useful when a query may return more resources than what is practical for performance and parsing. The syntax for pageSize is:

pageSize=n

where n is the maximum number of resources per page. For example:

GET /activities?pageSize=20

Every resource type has a default pageSize. This value is used when the query does not specify a pageSize. You can specify a pageSize less than or greater than the default pageSize.

Also, every resource has a maximum pageSize, and you cannot execute a query with a pageSize larger than the maximum.

For example, suppose a given user has 125 activities, and the activities resource has a default pageSize of 25 and maximum pageSize of 100.

  • GET /activities returns the first 25 activities (using the default pageSize value).
  • GET /activities?pageSize=10 returns the first 10 activities.
  • GET /activities?pageSize=30 returns the first 30 activities.
  • GET /activities?pagesize=120 returns an error because the value for pageSize exceeds the maximum for the resource.

The pageSize values for a resource defaults to defaultPageSize=25 and maxPageSize=100. Individual resources may override these values in the API's apiconfig.yaml file. (For example, in shared_ext-1.0.apiconfig.yaml, the AccountActivityPatterns resource overrides the default values and uses defaultPageSize=100 and maxPageSize=500.)

Specifying page size for included resources

For information on how to use the pageSize parameter with included resources, see Query parameters for included resources.

The self link returns a single resource in a page

When a response payload contains a collection, every element in the collection is listed in the data section of the payload. For every element, there is a links section that contains endpoints relevant to that element. One of the links is the self link. For example:

{
    "attributes": {
        ...
        "id": "cc:32",
        ... },
        ...
    "links": {
        ...
        "self": {
            "href": "/common/v1/activities/cc:32",
            "methods": [
                "get",
                "patch"
            ]
        }
    }
}

The href property of the self link is an endpoint to that specific element. When necessary, you can use this link to construct a call to act on that element.

pageOffset pages through resources

Whenever a response payload includes some but not all of the available resources, the payload also include a collection-level links section at the bottom. These links provide operations and endpoints you can use to act on a specific page of resources. (In the following descriptions, N is the pageSize of the query.)

  • The first link is an endpoint to the first page (the first N elements).
    • This appears for all collections.
  • The prev link is an endpoint to the previous page (the N elements before the current set of elements).
    • This appears if there are elements earlier than the elements in the payload.
  • The next link is an endpoint to the next page (the N elements after the current set of elements).
    • This appears if there are elements later than the elements in the payload.
  • The self link is an endpoint to the current page (the current set of elements).
    • This always appears (for elements and for collections).

For example, suppose there are 25 activities assigned to the current owner. The response payloads have a pageSize of 5, and a specific payload has the second set of activities (activities 6 through 10). The collection-level links for this payload would be:

"links": {
    "first": {
        "href": "/common/v1/activities?pageSize=5&fields=id",
        "methods": [
            "get"
        ]
    },
    "next": {
        "href": "/common/v1/activities?pageSize=5&fields=id&pageOffset=10",
        "methods": [
            "get"
        ]
    },
    "prev": {
        "href": "/common/v1/activities?pageSize=5&fields=id",
        "methods": [
            "get"
        ]
    },
    "self": {
        "href": "/common/v1/activities?pageSize=5&fields=id&pageOffset=5",
        "methods": [
            "get"
        ]
    }
}

To access a collection that starts with a specific resource, Cloud API uses a pageOffset parameter. This parameter is used in the prev and next links for a collection. The pageOffset index starts with 0, so a theoretical pageOffset=0 would start with the first element and pageOffset=5 skips the first 5 elements and starts with the sixth.

Note: There can be some complexity involved in determining how to construct a link with the correct pageOffset value. Therefore, Guidewire recommends that you use the prev and next provided in response payloads and avoid constructing pageOffset queries of your own.
Note: pageOffset is supported for root resources only. When executing a query that uses request inclusion, you cannot use pageOffset to page through included resources.

includeTotal retrieves the total number of resources

When querying for data, you can get the total number of resources that meet the criteria. To get this number, use the following syntax:

includeTotal=true

When you submit this query parameter, the payload includes an additional total value that specifies the total. For example:

"total": 72

When the includeTotal query parameter is used, the response payload contains two counting values:

  • count - The number of resources returned in this page.
  • total - The total number of resources that meet the query's criteria.

If the total number of resources that meet the criteria is less than or equal to the pageSize, then count and total are the same. If the total number of resources that meet the criteria is greater than the pageSize, then count is less than total. count can never be greater than total.

For performance reasons, Guidewire will count the total number of items up to 1000 only. When the total value is stated as 1000, the actual count could be 1000 or some number greater than 1000.

Note: If the number of resources to total is sufficiently large, using the includeTotal parameter can affect performance. Guidewire recommends you use this parameter only when there is a need for it, and only when the number of resources to total is unlikely to affect performance.

In some situations, you may be interested in retrieving only the total number of resources that meet a given criteria, without needing any information from any specific resource. However, a GET cannot return only an included total. If there are resources that meet the criteria, it must return the first N set of resources and at least one field for each resource. For calls that are sent to retrieve only the total number of resources, Guidewire recommends using a call with query parameters that return the smallest amount of resource information, such as GET ...?includeTotal=true&fields=id&pageSize=1.

Including totals for included resources

For information on how to use the includeTotal parameter with included resources, see Query parameters for included resources.

Tutorial: Send a GET with the pageSize and totalCount parameters

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more information, see Tutorial: Set up your Postman environment.

Tutorial steps

  1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
    1. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
  2. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
  3. Specify Basic Auth authorization using user aapplegate and password gw.
  4. Enter the following and click Send:

    GET http://localhost:8180/pc/rest/common/v1/activities

  5. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
  6. Enter the following and click Send:

    GET http://localhost:8180/pc/rest/common/v1/activities?pageSize=10&includeTotal=true

Checking your work

Compare the two payloads. In the first payload, the count of activities included in the payload is 11. Also, there is no count for the total number of activities the endpoint could return. In the second payload, the count of activities included in the payload is 10. Also, the count for the total number of activities the endpoint could return is 11. (This appears at the end of the payload.)