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

  1. 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.
  2. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
  3. Specify Basic Auth authorization using user aapplegate and password gw.
  4. Enter the following and click Send:

    GET http://localhost:8180/pc/rest/common/v1/activities?fields=id,dueDate

  5. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
  6. 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.