Sorting and filtering the response from your REST API

Document created by ahkal01 Employee on Nov 6, 2014Last modified by ahkal01 Employee on Nov 7, 2014
Version 2Show Document
  • View in full screen mode

You can sort, filter, select specific attributes, limit the number of items and change the format (XML to JSON and vice-versa) of the response from your REST API.

This is supported for GET requests with responses in XML or JSON format.

 

You do this by passing system filter parameters, as described below, to your GET request.  You can combine these system filter parameters with each other as well as with your own

user parameters.

Hint: don't forget to start the system filter parameter with the character $.

 

The examples below are based on the Book API sample which you can find at https://github.com/DevTestSolutions/Book-API.

 

Sorting

If your response is a list of items, each with a number of attributes, you can sort the list on a given attribute using the $orderby, $orderby.asc or $orderby.desc system filter parameter.

The first two specify sorting in ascending order and the third one descending order.

 

For example, the API response to

GET /book

returns a list of books:

[

    { "idtype": "OCLC", "id": "9506808", "title": "The Wonderful Wizard of Oz", "author": "L. Frank Baum" },

    { "idtype": "OCLC", "id": "236914", "title": "Kim", "author": "Rudyard Kipling" },

    {"idtype": "ISBN", "id": "978-0-670-22026-7", "title": "Christine", "author": "Stephen King" }

]

 

GET /book?$orderby.desc=author

sorts the list in descending order on author.


Filtering

You can filter your list to contain only items which match a simple logical expression using the $filter parameter.

For instance,

GET /book?$filter=(title=*Wonderful*)

returns books with Wonderful in the title.

 

You can use the wildcard characters * to match any sequence of characters and ?  to match one character.


The comparison operators are =, !=, >, <, >= and <=.

If all values are numeric, numeric comparison will be performed. 

Otherwise, it will default to alphanumeric comparison.


Currently, only simple logical expressions are supported without AND or OR logical operators.


Select specific attributes

You can select the specific attributes to return for your items using the $select parameter.

For instance,

GET /book?$select=(title,author)

returns the list:

[

    { "title": "The Wonderful Wizard of Oz", "author": "L. Frank Baum" },

    { "title": "Kim", "author": "Rudyard Kipling" },

    {"title": "Christine", "author": "Stephen King" }

]


The $select parameter can also be used where the response is a single item, as opposed to a list of items.

E.g.,

GET /book/Christine?$select=(title,id)

returns only the attributes title and id for the book Christine.


Limiting number of items

You can limit the number of items returned in your list response using the $top parameter.

For instance,

GET /book?$top=2

returns the first two books in the list.


The $top parameter can also be used where the response is a single item.  In this case, it limits the number of attributes of the item which get returned.

E.g.,

GET /book/Christine?$top=1

returns only the first attribute of the book.

 

Converting between JSON and XML

If you created your API with the response in JSON format, you can convert the response into XML when issuing a GET request.

E.g.

GET /book?$format=xml

returns the list of books in XML format.


Likewise, if your API was created with the response in XML format, you can convert the response into JSON with $format=json.

Attachments

    Outcomes