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
|
|
|
Vary by call.
|
asc
or
desc
|
Sort results by the specified field, in
either ascending or descending order.
|
|
|
Vary by call.
|
asc
or
desc
|
Sort results by a field, either ascending
or descending, and then pass the results to the next sort.
|
|
|
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
|
|
|
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.
|
|
|
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
