The sort
query parameter
For endpoints that return collections, you can sort the elements in the collection. To do this, use:
sort=propertiesList
where propertiesList is a comma-delimited list of properties that support sorting for that endpoint.
For example, the following query returns all activities 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 Query parameters for 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
.
Overriding default sorts
Some collections have default sorts. For example, by default, Activities
collections are sorted by priority
and then by
subject
.
Default sorts in the base configuration are defined in
shared_core-1.0.apiconfig.yaml
. Custom default sorts (which could either
be overrides of base configuration sort orders or sort orders for custom endpoints) are
defined in shared_ext-1.0.apiconfig.yaml
. Both of these
apiconfig.yaml files started with a resources
section. Some of the collection resources have a defaultSort
property which
defines the sort order. For example, the following is the portion of
shared_core-1.0.apiconfig.yaml
where the default sort order for
Activities
is defined.
resources:
...
Activities:
resource: gw.rest.core.pc.common.v1.activity.ActivitiesCoreResource
defaultSort:
- priority
- subject
In the defaultSort
section, every field is preceded by a hyphen and a
space (- ). This first hyphen does not indicate descending order. If a field has a default
descending order, then the field name is preceded by a second hyphen and surrounded by
quotation marks. For example, a default sort on priority in descending order would appear as
- "-priority"
.
As discussed in the previous section, you can use the sort
query parameter
to override the default sort for a collection. You can also remove the default sort order by
specifying ?sort=*none
. When you do this, results are sorted based on their
id
value. This may improve performance when you are retrieving a large
amount of information from an endpoint with a default sort order and the column that the
sort is based on is not indexed.
For example:
- GET
/common/v1/activities
returns activities using the default sort (priority and then subject). - GET
/common/v1/activities?sort=priority
returns activities sorted by priority only. - GET
/common/v1/activities?sort=*none
returns activities sorted only byid
.
Sorting included resources
For information on how to use the sort
parameter with included
resources, see Query parameters for included resources.
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 by 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.