When you see sort-definition in a request URL in this reference, create a sort filter with a field name and a value describing how you want the results sorted, in this syntax:

 sort-field=value

Replace sort with any of these exact values: sort (for a single sort), sort1 (for the primary sort of two), or sort2 (for a secondary sort on the results returned by sort1).

The field variable defines the field you are sorting on. The fields you can use vary by call, so check the API reference for the call you are making.

The value is always asc (for ascending) or desc (for descending), defining the sequence of the results. Putting this all together, the parts of a sort filter are shown in the following table:

Sort Type

Field

Value

Description

sort

Vary by call.

asc or desc

Sort results by the specified field, in either ascending or descending order.

sort1

Vary by call.

asc or desc

Sort results by a field, either ascending or descending, and then pass the results to the next sort.

sort2

Vary by call.

asc or desc

When results returned by the primary sort are equal, such as same name or group, do a secondary sort by the specified field in either ascending or descending order.

Simple examples of sort-field=value, with one level of sort, look like this:

 sort-name=asc 
 sort-date=desc

The following table gives you more detail on how the sort values asc and desc work:

Value

Description

asc

Ascending order. For alphabetical lists, begin with A and end with Z. For lists ordered by number or date, start with lowest number or earliest date.

desc

Descending order. For alphabetical lists, begin with Z and end with A. For lists ordered by number or date, start with highest number or most recent date.

Your results may call for using both primary and secondary sorts with sort1 and sort2. For example, when calling principal-list to list principals, you can do a primary sort on the type field, and then a secondary sort on the name field (this way, all principals of a specific type are grouped together and then sorted by name in each group).

You would specify two levels of sort like this:

 sort1-type=asc&sort2-name=desc

See also

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy