Controlling pagination
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. A caller can use "previous" and "next" links to access additional payloads with the previous or next "page" of N resources. The practice of separating a list of resources into discrete groups that can be paged through 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.
Limiting the number of resources per payload
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 defaultpageSize
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 forpageSize
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 claim-1.0apiconfig.yaml
, the ActivityPatterns
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.
Selecting a single resource in a collection
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.
Paging 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 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.
Retrieving 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 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.
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
.
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.
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
- In Postman, start a new request by clicking the + to the right of the
Launchpad tab.
- On the Authorization tab, select Basic Auth using user aapplegate and password gw.
- In Postman, start a new request by clicking the + to the right of the Launchpad tab.
- Specify Basic Auth authorization using user aapplegate and password gw.
- Enter the following and click Send:
GET
http://localhost:8080/cc/rest/common/v1/activities
- Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
- Enter the following and click Send:
GET
http://localhost:8080/cc/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 25. 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 30. (This appears at the end of the payload.)