Paging, Sorting & Filtering Output

GET calls can return extensive data sets. Use the following parameters to narrow and control your results.

Request Parameters

Parameters can be included in the URLs of selected requests to set date ranges; filter, sort and paginate output; and otherwise modify the behavior of a request. All reports, and a few other calls, require fromDate and toDate parameters.

Request parameters are added following a question mark in the URL as shown:

curl -X GET  \
https://api.getgo.com/admin/rest/v1/accounts/{accountKey}/users?pageSize=10&offset=10&filter=(email="(?i).*JGould@jg.org.*") | (firstName="(?i).*Janis.*") | (lastName="(?i).*Gould.*")&ascending=firstName=true  \
-H 'Accept: application/json'
-H 'Content-type: application/json'
-H 'Authorization: Bearer ZlUe11FakEyCWxtOkeN3wk0uTKuL...'

IMPORTANT: The access_token is truncated. It is a large value.

• pageSize - Total number of records to return per page. If the records output exceeds page size, each page is truncated.
• offset - Default is 0, and starts at record zero. Must be a positive integer. An offset of 5 starts output at record 5.
• ascending - Returns records in ascending (lowest to highest) order based on the primary data index.
• descending - Returns records in descending (highest to lowest) order.
• filter - The filter request is a key-value pair. Wildcard * support in the filter value depends on the filter name being searched.
• attributeNames - The attributeNames parameter lets you to choose which fields will be returned in the response.

Pagination

GoToAssist-Corporate

All GET methods support HATEOAS (Hypermedia as the Engine of Application State) pagination of the responses when called with additional page and size parameters.

GoToAdmin

In order to request multiple pages, you will have to make multiple calls with different offset values. The client defines what a page means by providing a constant pageSize parameter. Coming back to my example with 50 users in an account. The client defines that one “page” contains 20 users and can then request one page after the other till it retrieved all users or just doesn’t use the parameters at all.

Pagination sets a specific page or interval of resources during bulk queries. The 'offset' and 'pageSize' request parameters can be used to perform pagination in REST calls. The 'offset' request parameter is the zero-based starting position of the page. The offset must be non-negative. If it goes beyond the bounds of the queried list, it will automatically be truncated to the index of the last item. The default offset is 0. The 'pageSize' request parameter determines the max length of thepage. It must be positive. If it goes beyond the bounds of the queried list given the offset, it will automatically be truncated to include all of the items beginning at the offset. The default offset is 1.

For example, the array [1, 2, 3] can be divided into the following pages: [1], [1, 2], [1, 2, 3], [2], [2, 3], and [3]. The pages have different offsets and page sizes. [1] has offset 0 and size 1. [2, 3] has offset 1 and page size 2. [3] has offset 2 and page size 1.

GoToWebinar

You can paginate GET calls with:

• an embedded list - contains a list of page resources
• a list of links to pages - links to first, previous, self and last page links
• pages - contains size, totalElements, totalPages, and number (page number) To use these options, you pass the pagination instructions in the URL.

Examples of pagination :

"_embedded": {
},

"_links": {
    "first": {
        "href": ""
    },
    "prev": {
        "href": ""
    },
    "self": {
        "href": ""
    },
    "last": {
        "href": ""
    }
},

"page": {
    "size": ,
    "totalElements": ,
    "totalPages": ,
    "number":
}

Sorting

To sort REST call results, use the 'ascending' request parameter with a url-encoded comma-separated list of key-value pairs. Each pair defines the ascending preference for a resource field. The order of the pairs controls the order in which sorting is applied. The equal '=' character url-encoded is '%3D' and the comma character ',' url-encoded is '%2C'. Any resource field can be referenced in a sorting expression. Resource fields are case-sensitive. Non-existent resource fields are evaluated as null. The sort is formatted as follows:

admin=false,email=true,firstName=true,lastName=true

To include this in a REST API call, the syntax would be:

ascending=admin%3Dfalse%2Cemail%3Dtrue%2CfirstName%3Dtrue%2ClastName%3Dtrue

Sort Comparisons Table

Example

The following call retrieves teams data, filtering for all teams with a teamName starting with “KTe”; returning only the teamName, portalKey and teamKey; and sorted first by teamName in ascending order, then by portalKey.

https://api.getgo.com/G2AC/rest/v1/teams?filter=teamName=KTe*&attributeNames=teamName,portalKey,teamKey&sort=teamName%20asc,portalKey

Filtering

Filter expressions are boolean expressions on resource or object fields and support match operators '=' and '!=' based on a regular expression as well as boolean operators '&' and '|' to combine match results. Use precedence terminals '(' and ')' to set evaluation order. Resource fields names must only include alphanumeric characters, dots '.', and underscores '_'. Regular expression strings must be surrounded by double quotes '"' and may include all characters except double quotes.

Any resource field can be referenced in a filter expression. Resource fields are case-sensitive. Non-existent and null resource fields are evaluated as empty string. See Java class pattern for regular expression syntax.

To perform filtering in REST calls, the 'filter' request parameter is required. The value of the parameter is a url-encoded filter expression. The equal '=' character url-encoded is '%3D', the double quote character '"' url-encoded is '%22', and the space character ' ' url-encoded is '%20'.

Examples

The following examples are for User object calls.

Resource field 'firstName' matches regular expression '.Joe.':

firstName = ".*Joe.*"

To include this in a REST API call, the syntax would be:

filter=firstName%20%3D%20%22.*Joe.*%22

Resource subfield 'settings.G2M.chatEnabled' matches regular expression 'true' or field 'admin' matches regular expression 'true':

settings.G2M.chatEnabled ="true"| admin ="true"

Resource field 'admin' matches 'true' and 'firstName' matches '[a-z]' or 'admin' matches 'false' and 'lastName' not matches '[a-z]':

(admin ="true"& firstName = "[a-z]+") | (admin ="false" & lastName !=
        "[a-z]+")

Resource field 'groupKey' matches regular expression '123':

groupKey = "123"

Example Request Parameters:

offset=50&pageSize=10

Parameter Syntax

The following is an example of the parameters syntax in a call (in curl format) using the search terms firstName = Janis, and lastName = Gould. The search terms are added following the ?:

curl -X GET  \
https://api.getgo.com/admin/rest/v1/accounts/{accountKey}/users?pageSize=10&offset=10&filter=(lastName="(?i).*Gould.*")&ascending=name%3Dtrue
 -H 'Accept: application/json' \
 -H 'Content-type: application/json'  \
 -H 'Authorization: OAuth ZlUe11FakEyCWxtOkeN3wk0uTKuL...'