Following on from my resource output format options post in my OData series. I thought I would briefly cover the topic of URI Conventions I had previously eluded to.
URI Conventions for OData allow for a simple standard way to control the resource that is returned. The documentation for these conventions can be found here on the OData.org site.
The first important choice being the result format. In my previous post I discussed the options of AtomPub and JSON, the way you go about making your format choice for the returned resources is via the $format option. If your choice is JSON then simply suffix query option $format=JSON, for example on the NetFlix OData service:
In my experience with a few services the AtomPub choice is the default and the $format tag is not required, and in some cases (NetFlix in particular) $format=atom is not a valid input query. I’ll need to investigate this more, it seems like an oversight on at least the NetFlix service, I don’t see an issue with being more verbose even for a default value.
I also briefly mentioned deferred content and the use of $expand to force eager-loading of the result tree structure. This currently doesn’t seem to work on the NetFlix service, so this is yet another thing that will require some more investigation. It’s quite possible that the feature is disabled to prevent a type of attack (DoS) or just to prevent general abuse and waste of bandwidth/processing.
A simple convention is the $orderby option. It’s use is simple too and allows for chaining of various ascending and descending choices simply separated by commas.
http://odata.netflix.com/Catalog/Titles?$orderby=ReleaseYear,Runtime desc,Name asc
I believe the browser will replace the spaces with the ‘%20‘ representation. If you make a mistake in the query (i.e. supplying an invalid order field) the error will look like:
No property ‘Title’ exists in type ‘System.Nullable`1
The last three I want to cover are; $filter, $top and $skip. They are related as they simply filter the returned resource. Skip and Top are quite simple and operate as you would expect (just like in LINQ).
Filter on the other hand is more advanced; it has all the logic operator options (==, !=, >=, and so on), all the arithmetic operators (add, sub, div, mult, mod) and precedence grouping (brackets). For the exact syntax and all the options see the specification.
I’ll just give a simple example that can be clicked through:
http://odata.netflix.com/Catalog/Titles?$filter=Runtime gt 3 and Runtime lt 90
I did say last, but as a bonus there’s a nice data reduction option to return only the selected called $select. Simply suffix an &$select=Name,Runtime set of params on any of the above queries and see the returned resource simplified to only the “data you want”.
For the lazy to modify here’s a click-able example:
http://odata.netflix.com/Catalog/Titles?$filter=Runtime gt 3 and Runtime lt 90&$select=Runtime,Name
NOTE: OData queries are case sensitive.