by AJ Miller
3 Tips to Make Your Life Easier with oData
First a little background:
We recently had a client hire us to build an e-commerce platform for their new business model which had their business expanding from a retail brand to a retail brand with a team-based account-rep outlet. They had already done some research on some SaaS backends that would store the data and included all of the reporting/compliance tooling they needed. The final solution selected was through a company called Exigo. Exigo is a .Net solution with an API exposed through both SOAP and REST interfaces. Their REST API was implemented following a standard called oData.
Do you need help with a website or app project? While you are here, check out KnockMedia’s website and app services.
1. Use the ‘expand’ query parameter whenever possible
The Exigo API had support for products in a catalog (being an e-comm backend) which could each have sub-items (for products that had multiple colors, sizes, etc). If you needed to retrieve a product listing, in normal REST fashion you would post a GET request to: GET http://myapi.com/Items/1
The response would include a deferred URL like this:
{
"ItemID" : 1,
...
"GroupMembers" : {
"__deferred" : {
"uri" : "http://myapi.com/Items(1)/GroupMembers"
}
},
...
}
If you’re like me your first thought on how to retrieve group members for a product is to simply make a followup call to that deferred url. That solution definitely works, but now you have two roundtrips to the API. In our goal to create the most performant solution possible, we try to avoid multiple roundtrips as much as possible. oData has a solution to this relationship-fetching problem: the $expand parameter. By including a query parameter, you can retrieve the list of items, and all of their group members, in one request: GET http://myapi.com/Items/1?$expand=GroupMembers which will return the result of that deferred URL in the same place that the deferred URL once lived:
{
"ItemID" : 1,
"GroupMembers": {
"results" :
[{
"ItemID": 13,
"MasterItemID": 1,
"ItemCode": "1100C",
"MasterItemCode": "1000C",
"MemberDescription": "Group Member 1 - Blue",
"SortOrder": 1,
},
{
"ItemID": 24,
"MasterItemID": 1,
"ItemCode": "1200C",
"MasterItemCode": "1000C",
"MemberDescription": "Group Member 2 - Red",
"SortOrder": 2,
}]
},
}
2. Take advantage of server-side sorting using the ‘orderby’ query parameter
The REST service will return objects in a default order (usually just the object IDs in ascending order). If you need to display your data in any other order, say by post date, you can use the server to do the sorting by passing in an ‘orderby’ query parameter: GET http://myapi.com/Items?$orderby=ItemID desc and you’ll get the response ordered as you requested. This will also give you the ability to take advantage of any sort of query caching that may be done on the server without having to roll your own caching system.
3. Shrink your response package by utilizing the select query parameter
Since oData is tightly coupled to the database schema, you will often get back a full model when you request a resource. If your model consists of 100 attributes and you fetch 50 objects at a time, you’re effectively retrieving 5,000 attributes every time you make a request. You can limit the actual attributes that are returned, however, by specifying a ‘select’ query parameter and attaching a list of desired attributes. If you have a user model, retrieved via the url: GET http://myapi.com/Users/1, you may expect a return object like:
...
"UserID" : 1,
"FirstName" : "Bill",
"LastName" : "Anon",
"Email" : "bill@anon.com",
"AddressLine 1" : "123 Residential St."
"AddressLine 2" : "",
"City" : "Springfield",
"State" : "MA",
"Zip" : "21111",
...
}
If you really only care about the user’s first name and email address, however, the rest of the returned parameters are being wasted. They increase the size of the response package and they slow down both the serialization and deserialization of the data. By including a select query, we can return just the attributes we’re looking for: GET http://myapi.com/Users/1?$select=FirstName, Email and we’ll get a response that looks like:
{
...
"FirstName" : "Bill",
"Email" : "bill@anon.com",
}
This will speed up your deserialization and will be less strain on the battery life of any mobile devices using your app.
oData has had a troubled past, but it is still frequently deployed by SaaS providers who are based on the .Net platform. If you encounter it in your daily grind, hopefully these tips will help you get the most out of the interface. If you’d like to learn more about the options available in oData, the best source are the oData docs themselves.