Overview of query parameters
When you execute a system API call using only the endpoint (as in GET
/activities
), the response payload has a default set of resources and a
default structure.
You may want to refine the response payload beyond the default behavior by:
- Specifying a custom set of properties.
- Filtering out resources that do not meet a given criteria
- Sorting the resources
- Limiting the number of elements returned in each payload
- Retrieving a count of the total number of resources in the database that meet the query's criteria
You can refine the response payload using query parameters. A query parameter is an expression added to the HTTP request that modifies the default response payload.
A system API call can include any number of query parameters. The list of query parameters starts with a question mark (?). If there are multiple query parameters, each is separated by an ampersand (&). For example:
- GET
/activities?fields=*all
- GET
/activities?filter=escalated:eq:false
- GET
/activities?fields=*all&filter=escalated:eq:false
Included resources
You can use the include
query parameter to include resources related to
the primary resources of the response. You can also use query parameters to specify a custom
set of properties for included resources, filter out included resources that do not meet a
given criteria, sort the included resources, and so on. For more information, see Using query parameters on included resources.
Viewing query parameter documentation in Swagger UI
For every endpoint, Swagger UI provides descriptions of the query parameters supported by that
endpoint. This information is hidden by default. To show the descriptions, click the
endpoint's operation button (such as the GET button for GET
/activities
). The query parameter descriptions appear under the
endpoint.
Parameter definitions
The Parameters section describes each query parameter.
Supported parameters
The Responses section include a Model tab.
This tab provides information about the fields that support particular query parameters. For
example, you can sort results on some fields, but not all of them. The fields that support
sorting appear in the model with the text "sortable": true
.
Query parameter error messages
If you attempt to use a query parameter on a field that does not
support that parameter, the system API returns a 400 Bad Request error and an error message.
For example, if you execute: GET /activities?sort=escalationDate
, the system
API provides the following error message:
"message": "The sort column 'escalationDate' is not a valid option. The valid
sort options are [assignedUser, dueDate, escalated, priority, status, subject],
optionally prefixed with '-' to indicate a descending sort."