The sort query parameter

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

Potentially large endpoints

Some GET endpoints that retrieve a collection retrieve the data from database tables that are relatively large. The database query that retrieves the members of the collection may perform poorly if a sort is requested on these collections and if the sort cannot make use of an appropriate backing index.

To alert insurers to potentially bad performance, these endpoints are coded internally as being "potentially large". If a request on a potentially large endpoint attempts to sort on columns that do not match a backing index and the query returns too many results, the request is rejected with an error message telling the caller to add additional restrictions to the query and/or to remove the sorts.

The list of potentially large endpoints includes the following. Note that this list may not be exhaustive.