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 pagepageOffset
- specifies which page of resources to returnincludeTotal
- 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 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 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.
pageOffset
value. Therefore, Guidewire recommends that you use the
prev
and next
provided in response payloads and avoid
constructing pageOffset
queries of your own.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.
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
- 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:8180/pc/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: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.)