Sorting the result set
For endpoints that return collections, you can sort the elements in the collection. To do this, use:
?sort=properties_list
where properties_list is a comma-delimited list of properties that support sorting for that endpoint.
For example, the following query returns all activities assigned to the current caller and sorts them by due date:
GET /activities?sort=dueDate
You can specify multiple sort properties. Resources are sorted based on the first property. Any resources with the same value for the first property are then sorted by the second property, and so on. For example, the following query returns all activities assigned to the current caller and sorts them first by escalation status and then by due date:
GET /activities?sort=escalated,dueDate
You can also use the sort query for related resources added through the include parameter. For more information, see Using query parameters on included resources.
Sort orders
The default sort order is ascending. To specify a descending sort, prefix the property name with a hyphen (-). For example, the following queries return all activities assigned to the current caller, sorted by due date. The first query sorts them in ascending order. The second sorts them in descending order.
GET /activities?sort=dueDate
GET /activities?sort=-dueDate
Determining which values you can sort on
For a given endpoint, you can identify the attributes that are sortable by reviewing the
endpoint Model in Swagger UI. If a field is sortable, then the schema
description of the field includes the text: "sortable": true
.
For example, the following is the schema description for two fields returned by the Common
API's /activities
endpoint.
escalated boolean
readOnly: true
x-gw-extensions: OrderedMap { "filterable": true, "sortable": true }
escalationDate string($date-time)
x-gw-nullable: true
Note that the escalated
field includes the "sortable":
true
expression, but the escalationDate
field does not. This
means that you can sort on escalated
, but not
escalationDate
.
Tutorial: Send a GET with the sort query parameter
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.
In this tutorial, you will execute two requests to GET activities. The first does not sort the responses. The second does. To make it easier to compare the order of activities, each request retrieves only the ID and due date of each activity.
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?fields=id,dueDate
- 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?fields=id,dueDate&sort=dueDate
Checking your results
Compare the two payloads. In the first response payload, the activities are not sorted. In the second response payload, the activities are sorted by due date.