Sorting

You can use the orderBy parameter when retrieving a list of resources using the GET method to sort the returned list by the specified attribute in ascending or descending order.

• You can specify an ascending sort order or descending sort order using a + sign (ascending) or - sign (descending) before the attribute name. An ascending sort order is used if the sort order is not specified.

  Examples:

  • GET /rest/v1/receipts?orderBy=date lists receipts and sort them in ascending order of receipt date (oldest first).

  • GET /rest/v1/receipts?orderBy=+date lists receipts and sort them in ascending order of receipt date (oldest first).

  • GET /rest/v1/receipts?orderBy=-date lists receipts and sort them in descending order of receipt date (most recent first).

• The Sorting feature supports single level sorting only. Entering a comma-separated list of attributes will return an error. A secondary sorting level by internal ID is applied by default. When reading a list of receipts sorted by date, for example, if two receipts have the same receipt date, the response lists the receipt with the lower internal ID (id) first.

• The Sorting feature supports standard indexed fields only. See Sortable fields.

• Sorting by a hidden sortable field is allowed. The returned list of resources is sorted in the order specified even if the sortable field is hidden due to form permissions, form permission rules or other account configuration setting.

Sortable fields

The Sorting feature supports standard indexed fields only. The field descriptions in the Generated API Documentation JSON or the REST API Endpoint Reference indicate whether you can sort the list of resources by the field. Look for the [Sorting allowed] mention in the schema object field descriptions.

Parameters

Parameter	Description
orderBy	The attribute to sort the list by. The attribute must be sortable – Look for the [Sorting allowed] mention in the schema object field descriptions. Use a plus sign (+) or minus sign (-) before the attribute name to specify an ascending (+) or descending (-) sort order. An ascending sort order is used if the sort order is not specified.

Response

A sorted list of resources. The response includes the meta property in the JSON-encoded object returned. For a sorted response, the meta property has the following attribute in addition to other relevant attributes (see also Pagination, for example).

Property	Description
orderBy	An array of one object containing the following properties: reversed — true if the list is sorted in descending order, or false if the list is sorted in ascending order. field — the attribute used to sort the list by.

Example

The following example returns a page of 5 receipt objects in descending order of receipt date.

Request:

            GET /rest/v1/receipts?orderBy=-date&fields=date,id&limit=5 HTTP/1.1 

          

Response:

            {
   "message" : "success",
   "data" : [
      {
          "date": "2022-10-03",
          "id": 146
      },
      {
          "date": "2022-10-03",
          "id": 152
      },
      {
          "date": "2022-10-03",
          "id": 186
      },
      {
          "date": "2022-09-26",
          "id": 116
      },
      {
          "date": "2022-09-23",
          "id": 98
      }
   ],
   "meta" : { "rowsPerPage": 5,
      "totalPages": 44,
      "totalRows": 9,
      "orderBy": [
         {
            "reversed": true,
            "field": "date"
         }
      ],
      "links": [
         {
            "rel": "self",
            "href": "https://company-id.app.openair.com/rest/v1/receipts?orderBy=-date&fields=date,id&limit=5"
         },
         {
            "rel": "next",
            "href": "https://company-id.app.openair.com/rest/v1/receipts?orderBy=-date&fields=date,id&limit=5&offset=5"
         },
         {
            "rel": "last",
            "href": "https://company-id.app.openair.com/rest/v1/receipts?orderBy=-date&fields=date,id&limit=5&offset=40"
         }
      ]
   }
}