Controlling pagination

GETs that return collections typically return multiple root resources. You can use the pageSize parameter to limit the number of root resources returned in a given payload. This can be useful when a query may return more resources than what is practical for performance and parsing. To limit the number, use the following syntax:

pageSize=n

where n is the maximum number of resources per payload to return. 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.0apiconfig.yaml, the AccountActivityPatterns resource overrides the default values and uses defaultPageSize=100 and maxPageSize=500.)

You can also use the pageSize query for related resources added through the include parameter. For more information, see Using query parameters on included resources.

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.

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 N elements.
  • This appears for all collections.
• The prev link is an endpoint to 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 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 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, the system APIs use 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.

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.

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 payload.
• 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. If a total value is equal to 1000, the actual count could be 1000 or some number greater than 1000.

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.

You can also use the includeTotal query for related resources added through the include parameter. For more information, see Using query parameters on included resources.

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.