Ordering

Summary

In addition to filtering the API will also allow you to change the order in which results are returned. In this guide we'll take a look at the ways in which data can be sorted and how to select the data that it is sorted on.

Basic Sorting

In order to sort the data you first need to decide the property that you want to sort on - any property on an object can be used to sort as long as it is a primitive type (such as a string, number or boolean) and not another object. The name of this property can then be passed using the `sort` parameter in the query string along with the URL.

For example, if we wanted to return all the companies ordered by name we would send the following request:

curl -H "Authorization: ApiKey {ApiKey}" "https://api.youmanage.co.uk/companies?sort=+Name"
[
  {
    "id": 7,
    "name": "Awesome Inc.",
    "enabled": false
  },
  ...
]

You'll notice that we also prepended the name of the property with the plus symbol. That informs the API that we wish to sort the data by name in ascending order, conversely, if we wanted to sort in descending order then you can prepend the name of the property with the minus symbol.

curl -H "Authorization: ApiKey {ApiKey}" "https://api.youmanage.co.uk/companies?sort=-Name"
[
  {
    "id": 2,
    "name": "Fictional Data Limited",
    "enabled": true
  },
  ..
]

This covers the basic cases of sorting data, next we'll look at compound sorting.

Multiple Sorting

There are some cases where you will want to sort on more than one property and this is done by chaining simple sorts as before. For example, if we wanted to sort all companies firstly by their status with enabled companies first (achieved by the basic sort `-Enabled`) and then by alphabetically by name (same basic sort as in the previous example, `+Name`) we would pass the two basic sorts separated by a comma to the `sort` parameter:

curl -H "Authorization: ApiKey {ApiKey}" "https://api.youmanage.co.uk/companies?sort=-Enabled,+Name"
[
  {
    "id": 2,
    "name": "Fictional Data Limited",
    "enabled": true
  },
  {
    "id": 5,
    "name": "Youmanage HR",
    "enabled": true
  },
  {
    "id": 7,
    "name": "Awesome Inc.",
    "enabled": false
  }
  ..
]

You can chain as many sort definitions as you require but note that if a property features multiple times then it will be ignored after the first reference.