Ctrl+K

Filtering & Sorting

Filtering & Sorting#

When an endpoint returns a list of items, it often supports filtering and sorting the response.

Note

Not all endpoints that return lists support filtering and sorting. For details about a specific endpoint, refer to its documentation.

Filtering#

To return only items that meet specific criteria, use the $filter query parameter to provide the properties of the items to include. For example, you can filter a list to include only items with a specific status or type. In order to filter for a value that contains a single quote ('), escape it using an additional single quote.

The $filter parameter supports these conditional predicates and operators:

  • Equal to (eq)

  • Not equal to (ne)

  • Less than (lt)

  • Greater than (gt)

  • Less than or equal to (le)

  • Greater than or equal to (ge)

  • And (and)

  • Or (or)

  • Not (not)

  • In (in)

$filter Examples#

$filter=status eq 'Created' and title contains 'TODO'
$filter=status in ('Created', 'Completed')
$filter=dueDate gt 2022-09-15T14:00:00Z

Example call using $filter#

curl -X GET "https://api.app.wdesk.com/platform/v1/tasks" \
    -G  --data-urlencode "\$filter=status eq 'Created' and title contains 'TODO'" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer {access-token}"

http GET https://api.app.wdesk.com/platform/v1/tasks  \
    \$filter=="status eq 'Created' and title contains 'TODO'" \
    Accept:application/json \
    Authorization:"Bearer {access-token}"

wget --method=GET "https://api.app.wdesk.com/platform/v1/tasks?\$filter=status eq 'Created' and title contains 'TODO'" \
    --output-document -  \
    --header "Accept: application/json" \
    --header "Authorization: Bearer {access-token}"

Sorting#

To indicate the order in which to sort the items, use the $orderBy query parameter.

  • To sort items based on criteria such as type or status, provide one or more comma-separated expressions.

  • To sort items in ascending or descending order, use asc or desc, respectively; asc is default.

$orderBy Example#

$orderBy=title asc

Example call using $orderBy#

curl -X GET "https://api.app.wdesk.com/platform/v1/tasks" \
    -G  --data-urlencode "\$orderBy=title asc" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer {access-token}"

http GET https://api.app.wdesk.com/platform/v1/tasks  \
    \$orderBy=="title asc" \
    Accept:application/json \
    Authorization:"Bearer {access-token}"

wget --method=GET "https://api.app.wdesk.com/platform/v1/tasks?\$orderBy=title asc" \
    --output-document -  \
    --header "Accept: application/json" \
    --header "Authorization: Bearer {access-token}"