The idea of this blog is simple. This blog is an effort to simplify OData and help beginners understand and start adopting the standard for their development needs.
When I started off with trying to break down and understand OData, I found the internet a big world to get lost in. If you are one of those, patient enough to read through precise technical details, then http://www.odata.org will be the best place to learn OData.
In this blog, I will try to summarize OData into a crash course version for those who like me come with a lazy attitude towards reading online documentation. To keep this a blog easily readable by beginners, I will try to keep the discussion of OData to 10 short sections that I personally believe is what we need to know as to get our basics clear.
Note: I will use the various references inline with the odata.org site so that it might be easier for readers to refer back to the website for further details and keep the context alive.
Lets start with
1. What is OData?
The simplest definition of OData would be that it is a standardized protocol built over existing HTTP and REST protocols supporting CRUD (Create, Read, Update, Delete) operations for creating and consuming data APIs.
Nickname: ODBC for the Web
2. Entity Data Model and an OData metadata
The metadata of an OData message can be summarized as below;
An OData metadata will contain the definition of Entity Sets and the associations. An entity set is nothing but a collection of Entity Type. An entity type can be considered as a data type that contains details of a specific type of data ex. Customer, Supplier, Sales Order, Employee etc.
You would have already figured out that an entity key is used to uniquely identify an entity type. Ex. Employee number, Sales Order number, Product ID etc
Now an association is simply the relationship between two or more entity types. A good example for association would be Products to its Manufacturer. An entity set Product can be associated with an entity set Manufacturer in an OData metadata.
A navigation property then is nothing but a property set on an entity type to understand the associations of the entity type.
3. Access an OData service
We access and OData service via an URI
4. How do I understand/access the metadata model of the above service?
Add the suffix to the service URI- $metadata
5. Lets talk details please!
If we deep dive into the OData service referred earlier, we find that there are four Entity sets i.e Four different types of data returned by the service.
Now to understand more about this, we will have to look into the metadata and see what information it reveals.
Below we see how the metadata revels the Entity type to Entity set relationship;
To understand the relation between each of the Entity sets and Entities, refer the below;
The above means that for particular item in the Products Entity set, we can refer its Category or its Supplier. Similarly for a particular Supplier in the Supplier entity set (Suppliers), we can get a Product set (Products) and for a particular Product from that set, can further extract it's category.
In the case of Categories, for a Particular Category, we can extract a Product set (Products) related to it and further also extract the supplier for a specific product.
6. OK, enough with the pictures. Show me the real stuff now!
6.A. How do I access an Entity set?
If you want to access say the Categories entity set, use the URI - http://services.odata.org/OData/OData.svc/Categories
This will return the entire Categories available with the service. You will find three Categories returned, Food, Beverages and Electronics.
6.B. How do I access a particular entity in an entity set?
You can refer the entity key in the URI to access the particular record. Ex. in the above service for a specific category, we can refer it with its ID. From the above URI, lets access only the beverages category. The id for Beverages is 1. So we can use the following URI to access that specific record;
Note: How do I know what's the entity key?
In the metadata, for the Entity type definition, you can find the Key referenced. In the case of Category, it is the field 'ID'.
6.C. Show me an example of the associations and navigation between Categories, Products and Suppliers.
The above link can be interpreted as finding the Supplier of Product with ID = 2 within the Categories entity set with the Category ID as 1.
7. So what are the queries I can use to manipulate the data?
The below table will document the most used and helpful queries when dealing with an OData service;
|$format||By default you would have noticed that the data returned is in an XML feed. This query allows us to change the format of data. The example here shows how you can return all the suppliers returned by the service in JSON format instead of XML.||http://services.odata.org/OData/OData.svc/Suppliers?$format=json|
|$top||This query option helps to limit the data returned by the service. The example here shows how you can return only the 1st Category instead of all the Categories.||http://services.odata.org/OData/OData.svc/Categories?$top=1|
|$skip||This can be treated as the opposite of $top. The skip queries can be used to skip records. The example here shows how you can skip the first 2 records in the Products set and return the rest of products. Hence on the execution of the given query, Products with ID as 0 and 1 gets skipped.||http://services.odata.org/OData/OData.svc/Products?$skip=2|
|$inlinecount||This will return the total number of records as part of the response payload. We can extract the number from the field <count></count>. If you execute the given example, in the payload you will find that in the field <count>, the value is returned as 2, meaning there are total 2 Suppliers as part of the service.||http://services.odata.org/OData/OData.svc/Suppliers?$inlinecount=allpages|
|$orderby||Use this to sort the records returned by the service. The given example shows how to sort the Product entity set by the price of each product. Here Price is a field returned as part of the Product set. On use of the query, the record set is returned with the ascending order of Price. You can use a suffix desc to return the records in the descending order.|
|$expand||This I found to be a very helpful query to reduce the number of calls we need to make to access a particular set of data. Say, in case you want to return all the products along with their Category, use the URL provided in the example.||http://services.odata.org/OData/OData.svc/Products?$expand=Category|
|$filter||This can be compared to the 'where' query in SQL. Lets say we want to get all the products with rating greater than 3, then use the example as defined here. Note that we can use both Logical and Arithmetic operators. There are also various functions like substring etc that is supported. Please refer this link for the extensive list that you can use.|
As in any SQL query, this query option can be used to Select specific or all fields of an Entity set or entity. A simple example, lets say the requirement for which is for us to return the fields rating and Price of a Product with ID = 3
Note: I found that it is not possible to use $select on Complex types. For example, the Address is a complex type in the Entity Supplier. So if we want to say, select the City and State which are the fields part of the Address structure, the $select is not supported. (Or am I struggling to use it correctly?)
a. Get me the three of the best rated products
b. Ok! Now get me the next three best rated products.
c. Get me the count of Products with the Price greater than or equal to 20?
8. Instead of a browser, are there any tools I can use to play around with OData?
Yes. One simple tool is the Advanced REST Client for Chrome. There are also many other clients available online for free which help you.
9. What was all the CRUD thing about?
In case of OData, CRUD operations are defined as POST (Create), GET (Read), PUT (Update) and Delete (Delete) HTTP methods.
You can do a GET and POST request on an Entity Set while GET, PUT and DELETE can be done on an Entity.
10. This is all good but why OData instead of normal REST?
Well, you have seen how OData provides you with a consistent uniform standard way of describing the data and the data model. That precisely gives it an edge over REST. Moreover, hey SAP seems to be investing heavily on the standard. Which might mean, like it or not, you will eventually end up using OData
Hope this was an enjoyable read. Please do leave a feedback or comment on anything you wish to see changed or added additionally.