In my previous tutorial we’ve covered different aspects of how to Build RESTful service using Asp.NET Web API, in this multi-part series tutorial we’ll be building OData service following the same REST architecture we’ve talked about previously.
Before jump into code samples let’s talk a little bit about OData definition and specifications.
OData Introduction
OData stands for Open Data Protocol. It is standard to for providing access to data over the internet, OData is championed by Microsoft as an open specification and adopted by many different platforms. By using OData it will allow you to build a uniform way to expose full featured data APIs (Querying, Updating), the nice thing about OData that it builds on top of mature standard web technologies and protocols such as HTTP, Atom Publishing Protocol, JSON, and follow the REST architecture in order to provide data access from different applications, services and data stores.
It is well known that any service follows the REST principles well adhere to the aspects below:
- Resources are identified by a unique URI only.
- Actions on the resource should be done using using HTTP verbs (GET, POST, PUT, and DELETE).
- Enable content negotiation to allow clients specifying the format of the data type returned: XML format (AtomPub), or JSON format (Verbose/Light).
Querying Existing OData Service
Before start building our OData service let’s examine querying an existing OData service published on the internet and uses the Northwind database, the base URI for this service is http://services.odata.org/Northwind/Northwind.svc. You can use any REST client such as (Fiddler, PostMan) to compose those HTTP requests, as we are only querying the service now (No sending updates) you can use your favorite browser as well. Note you can use Linq4Pad to generate and test complex OData qyeries
The tables below illustrates some of the OData query options which can be used to query the service:
Option | OData Service URL | Notes |
---|---|---|
$filter | http://services.odata.org/Northwind/Northwind.svc/Products?$filter=ProductName eq 'Tofu' | Filter the results based on Boolean condition, I.e. get product name = 'Tofu' |
$orderby | http://services.odata.org/Northwind/Northwind.svc/Products?$orderby=ProductName | Sort the results, i.e: Sort the products by Product Name |
$skip | http://services.odata.org/Northwind/Northwind.svc/Products?$skip=10 | Skip the first n results, used for server side paging |
$top | http://services.odata.org/Northwind/Northwind.svc/Products?$top=10 | Returns only the first n the results, used for server side paging |
$select | http://services.odata.org/Northwind/Northwind.svc/Products?$filter=ProductName eq 'Tofu'&$select=ProductName,UnitPrice | Select which properties to be returned in the response. i.e. returning ProductName and UnitPrice |
$expand | http://services.odata.org/Northwind/Northwind.svc/Products?$expand=Supplier | Expand the related entities inline i.e. expand the supplier entity for each product |
$inlinecount | http://services.odata.org/Northwind/Northwind.svc/Products?$inlinecount=allpages | Inform the server to return the total count of matching records in the response. |
As we see in the table above we can combine different query options together and provide complex search criteria for example if we want to implement server side paging we can issue the following HTTP GET request: http://services.odata.org/Northwind/Northwind.svc/Products?$top=10&$skip=0&$orderby=ProductName&$inlinecount=allpages where $skip represents the number of records to skip usually (PageSize x PageIndex) and $inlinecount represents the total number of products. To view the complete list of available query options you can visit this link.
As we stated before OData service allows content negotiation, so the client can choose the response format by setting the Accept header of the request, each response format has its own pros and cons, the table below illustrates the differences:
XML (Atom Publishing) | JSON Verbose | JSON Light | |
---|---|---|---|
OData Version | Version 1, 2, and 3 | Version 1, 2 and 3 | Version 3 |
Metadata and Hyper Links | Data and MetaData | Data and Metadata | No Metadata, Just the Data |
Payload Size for all Products entity | 28.67 KBs | 14.34 KBs, smaller by 50% | 4.25 KBs, smaller by 75% |
Easy to consume in mobile clients | No | Yes | Yes |
Accept Header | application/atom+xml | application/json;odata=verbose | application/json |
I’ve decided to split this tutorial into four parts as the below:
- OData Introduction and Querying Existing OData Service – Part 1 (This Post).
- Create read-only OData endpoint using Asp.Net Web API – Part 2.
- CRUD Operations on OData endpoint using Asp.Net Web API – Part 3.
- Consuming OData Service using AngularJS and Breeze.js – Part 4 (Coming Soon).
Source Code for this series is available on GitHub, you can download it locally or you can fork it. If you have any question or if there is nothing unclear please drop me a comment.
Hello sir your tutorial is very much helpful for me, but how could I write a custom method in Odata Controller instead of HTTP verbs ?
These posts are helping a lot to understand how to put various things together for a solid Web API implementation. We don’t think ASP.NET 5 is ready for prime time yet – so we will use this older style Web API 2. However, conflicted about whether or not to use OData. I am new to OData and these MS technologies in general. So, from a high level, OData can reduce us writing filtering and pagination code but authentication, authorization and other things you’ve included in the non-OData implementation will and can be done with OData – right? Any other thoughts on the pros and cons of using OData would be greatly appreciated.
Hi RT,
OData is never responsible for Auth and AuthZ, it is used for the scenarios you already stated, if you need to secure and look your Web API service then you need to implement what I have done on the other posts or use stand alone STS server such as Thinktecture Identity server.
Thanks Taiseer. In general, I am a bit confused about whether I should fully use Web API or OData or a mix of the two in my project. It could be that there is complex business logic to be done in the backend, before making calls to the data tables as opposed to simple CRUD where Web API might be more flexible. For example, if let’s say I want to upload a file to Azure storage also, will OData let me access the uploaded data from the Controller? If I use a mix of the two, then it is not as elegant – as the client side may have to build the HTTP requests differently for different API requests and I’d like to avoid having two types of paths in the code if possible. Can you comment on how flexible OData is before I end up committing fully to trying and doing everything in OData? Thanks.
Hi RT,
I never used OData in real enterprise project, bit I believe you might face some complications down the road if you used OData and you need to implement some custom business logic. So it depends on your case and how complex your API is.
I wonder how can we implement OAuth with bearer based token as I have built MVC4 project and added Api area where I have implemented OData v3 to access entity set but I am looking to implement OAuth bearer based token for mobile app clients ( using username and password to access api controllers).