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
Type | Comparison |
---|---|
String | Locale-sensitive comparison |
Number | Numeric comparison |
Boolean | False < True> |
Array | Short array < long array>, if lengths are equal compare sorted items |
Null | Null < Non-null> |
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...'
- How much do the LogMeIn APIs cost?
- How do I get started?
- How do I get support for the APIs?
- Can I access more than one product API?
- What are the rate limits for the APIs?
- How to login or create a developer account
- How to create an OAuth client
- How to obtain an access token
- How to obtain and use refresh tokens
- How to use Postman API collections
- GoToWebinar webhooks
- How to use GoToWebinar webhooks
- How to use GoToConnect API to fetch Account Users and Lines
- Date and time conventions
- Paging, Sorting & Filtering Output
- OAuth Migration Guide
- Direct Login Migration
- Migrating from GoToConnect to LogMeIn Authentication API
- Introduction
- Java SDK
- .NET SDK
- SDK License Agreement