OData

OData Basics

Open Data Protocol is a web protocol designed by Microsoft with the aim to create a new protocol for querying and updating data over HTTP. OData is an Open protocol, which means that various implementation methods are available for it.

ASP.NET Web API has built-in support for OData so that you can query your resources using the HTTP protocol and the OData syntax. Complete support for Web API was added with the Visual Studio 2012 Update 2, or with the Microsoft ASP.NET Web API OData NuGet package.

We will now build a simple API with OData support.

Consider this controller:

This controller does not inherit from the usual ApiController, but instead is an EntitySetController. EntitySetController is an abstract class that inherits from ODataController, which inherits from ApiController.

The complete hierarchy is:

EntitySetController hierarchy

The EntitySetController is just a specialized ApiController that has built-in facilities to manage the OData requests and to build OData responses.

In the previous example, the controller is declared as EntitySetController<Post, int>. The two generic parameters represent the entity type exposed by this endpoint and the type of the entity Id. So the post class could be something like this:

Then we override the Get method of EntitySetController and implement it so that it returns the list as IQueryable<Post>. The IQueryable is needed by the OData controller, which uses it to add the query that is eventually provided in the GET request.

This is not enough to make the OData protocol work with the Web API; we need some more configuration. In the WebApiConfig class, we have to add this code:

This code creates and configures the OData endpoint and defines a new route for the OData requests. Please note that the new route won’t use the /api route, but instead will start with odata, as defined in the MapODataRoute. Another thing to note is that the URI in the previous case will be case sensitive, so the correct URI would become /odata/Posts.

The EnableQuerySupport command is necessary if we want to enable the query protocol of OData.

Now we are ready to launch the application and test the OData protocol:

A simple get to an OData Endpoint

The result is not so different from the one with the default ApiController. The only real difference is in the attribute odata.metadata that specifies a URL to which we can ask information about the Post resource. If we invoke that URI, we obtain:

Resource metadata

This XML describes the Post resource showing properties and its types other than general information about the entity.

However, the real power of OData is in the fact that you can generate requests using a special syntax that enables you to create complex queries to filter, order, and aggregate the results.

Let’s start by adding an order by clause to the URI:

/odata/Posts?$orderby=PublishingDate

The orderby option instructs the OData engine that we want the result ordered by publishing date. We do not have to modify the code, since the OData modules of the ASP.NET Web API parse the Query String and the filters are applied to the IQueryable result.

The currently supported options are: top, orderby, filter, inlinecount, and skip.

Orderby

orderby is used to specify how the result must be sorted. The default sorting is in ascending order, but we can specify the type of sort using this syntax:

/odata/Posts?$orderby=Author desc

We can also combine different attributes:

/odata/Posts?$orderby=Author,PublishingDate

Top

/odata/Posts?$top=2

top is used to specify the number of items to return. With $top=2, we are saying that we want just two elements.

Filter

/odata/Posts?$filter=Author%20eq%20'ema'

filter is used to restrict the result (like the “where” clause in SQL). In the this example, we requested the posts of the author “ema.”

filter can also be used with Boolean and comparison operators.

OData Boolean operators

With these operators, we can create more complex queries:

/odata/Posts?$filter=Author%20eq%20'ema'%20and%20Title%20eq%20'post2'

/odata/Posts?$filter=Author%20eq%20'ema'%20or%20Author%20eq%20'tessa'

Inlinecount

inlinecount is used to add information about the number of items in the collection:

/odata/Posts?$inlinecount=allpages

The allpages value is defined in the OData specification and MUST include a count of the number of entities in the collection identified by the URI (after applying any $filter system query options present on the URI).

Skip

Skip is used to skip the first n values and return only the next:

/odata/Posts?$skip=2

In this example, skip returns only the elements starting from the third element in the list.

OData is capable of much more than this; the protocol also specifies the way to modify resources, but the details are beyond the scope of this book.

Summary

OData is an interesting technology that can be used to query our API. Instead of creating many endpoints with various parameters to match the entire possible request, an OData endpoint resolves most of the problems in just a few lines of code. In this chapter, we saw how it works and the basic syntax used to build the queries.