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 by id.

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.
1. 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.

The sort query parameter