Learn about OData Fundamentals

You can understand OData as being the combination of two essential parts. The first is the format, the second is the protocol. The format defines how data is described, how it is serialized. The protocol defines how that data is manipulated.

The origin of OData’s format comes from the world of weblogs, blogging and syndication. The Rich Site Summary (RSS) format was defined to describe a blog and the posts available in it, typically with the newest posts first, but in XML format for machine consumption. It can also describe a set of posts collected in another context, for example all posts tagged with a certain value.

RSS is also known as “RDF Site Summary” or “Really Simple Syndication”.

Let’s look at an example of RSS. The National Aeronautics and Space Administration (NASA) maintains many RSS feeds, and you can see a list of them on the NASA RSS Feeds page. Go there now and select the Breaking News feed which is at this URL:

https://www.nasa.gov/rss/dyn/breaking_news.rss

The resulting RSS content of this resource should look something like this (reduced here for brevity):

<?xml version="1.0" encoding="utf-8"?>
<rss xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd" xmlns:media="http://search.yahoo.com/mrss/" version="2.0" xml:base="http://www.nasa.gov/">
  <channel>
    <title>NASA Breaking News</title>
    <description>A RSS news feed containing the latest NASA news articles and press releases.</description>
    <link>http://www.nasa.gov/</link>
    <atom:link rel="self" href="http://www.nasa.gov/rss/dyn/breaking_news.rss"/>
    <language>en-us</language>
    <item>
      <title>NASA Administrator to Visit Florida Students, Industry</title>
      <link>http://www.nasa.gov/press-release/nasa-administrator-to-visit-florida-students-industry</link>
      <description>NASA Administrator Bill Nelson will speak to elementary school students about the future of space exploration Monday, May 9, and tour a lab working on robotic construction technologies Tuesday, May 10, during a trip to Florida.</description>
      <enclosure url="http://www.nasa.gov/sites/default/files/styles/1x1_cardfeed/public/thumbnails/image/nasa-logo-web-rgb_0.jpg?itok=mrBnB_c9" length="189751" type="image/jpeg"/>
      <guid isPermaLink="false">http://www.nasa.gov/press-release/nasa-administrator-to-visit-florida-students-industry</guid>
      <pubDate>Fri, 06 May 2022 11:13 EDT</pubDate>
      <source url="http://www.nasa.gov/rss/dyn/breaking_news.rss">NASA Breaking News</source>
      <dc:identifier>479411</dc:identifier>
    </item>
    <item>
      <title>NASA, ESA Astronauts Safely Return to Earth</title>
      <link>http://www.nasa.gov/press-release/nasa-esa-astronauts-safely-return-to-earth</link>
      <description>NASA's SpaceX Crew-3 astronauts aboard the Dragon Endurance spacecraft safely splashed down Friday in the Gulf of Mexico off the coast of Florida, completing the agency's third long-duration commercial crew mission to the International Space Station.</description>
      <enclosure url="http://www.nasa.gov/sites/default/files/styles/1x1_cardfeed/public/thumbnails/image/nhq202205060003.jpg?itok=nJXN4A_c" length="3817815" type="image/jpeg"/>
      <guid isPermaLink="false">http://www.nasa.gov/press-release/nasa-esa-astronauts-safely-return-to-earth</guid>
      <pubDate>Fri, 06 May 2022 01:04 EDT</pubDate>
      <source url="http://www.nasa.gov/rss/dyn/breaking_news.rss">NASA Breaking News</source>
      <dc:identifier>479399</dc:identifier>
    </item>
  </channel>
</rss>

Observe the structure of the XML document. Within the outermost <rss> element, it describes a <channel> that has some metadata such as title and description. That <channel> contains one or more <item> elements, each of them representing a breaking news item.

rss
  |
  +-- channel
        |
        +-- item
        |
        +-- item
        |
        +-- ...

Think of this overall structure like a document, with a header and items.

Atom is a format very similar to RSS, serving the same purpose, and is properly known as the Atom Syndication Format. Some may call Atom a successor to RSS. Unlike RSS, which is just a format specification, Atom also has a related protocol called the Atom Publishing Protocol that enables the manipulation of data stored in Atom-formatted resources. This was useful for weblog authors, who could use tools that spoke the Atom Publishing Protocol to edit and publish posts to remote blogging systems.

Look at an example of the Atom format in the corresponding Wikipedia entry: https://en.wikipedia.org/wiki/Atom_(Web_standard) - follow the link in the “Contents” box to section 5 “Example of an Atom 1.0 feed”. Notice that the general structure of the elements is the same as RSS, consisting of a root feed element containing entry child elements.

The Atom Publishing Protocol Request For Comments (RFC) document (RFC5023) describes a series of standard operations that can be performed on entries in an Atom feed - in other words, operations on XML representations of blog posts that are in the form of XML entry elements. These operations are for listing multiple entries and creating, editing, retrieving & deleting individual entries, and they correspond to the standard HTTP methods (GET, POST, PUT and DELETE).

The Atom Publishing Protocol specification also details the concept of a service document that describes what collections of entries are available for a given resource. Here’s an example of a service document:

<?xml version="1.0" encoding='utf-8'?>
<service xmlns="http://www.w3.org/2007/app"
  xmlns:atom="http://www.w3.org/2005/Atom">
  <workspace>
    <atom:title>Main Site</atom:title>
    <collection href="http://example.org/blog/main" >
      <atom:title>My Blog Entries</atom:title>
      <categories href="http://example.com/cats/forMain.cats" />
    </collection>
    <collection href="http://example.org/blog/pic" >
      <atom:title>Pictures</atom:title>
      <accept>image/png</accept>
      <accept>image/jpeg</accept>
      <accept>image/gif</accept>
    </collection>
  </workspace>
</service>

You will see that these fundamental building blocks of Atom are alive and well in the OData protocol today.

The ideas in Atom formed the foundation of OData. OData is described in full at https://www.odata.org/ but at a simple level, OData has:

• a service document describing the data available in a given OData service
• the concept of entity sets and entities, which are direct parallels of feeds and entries, respectively, in RSS and Atom
• a basic set of operations: Create, Read, Update, Delete and Query (commonly referred to as CRUD+Q)

There is a publicly available set of OData services maintained by the OASIS organisation, which are known as the Northwind services because they offer a data set based on a business scenario that revolves around a company called Northwind Traders. This data set contains entities such as customers, products and suppliers.

Go to the OASIS OData sample service root URL https://services.odata.org/. You should see something like this:

Select the link Browse the Read-Only Northwind Service and you will see the XML contents of this resource: https://services.odata.org/V3/Northwind/Northwind.svc/. This is the service document for the OData service at this location, and the start of it should look like this:

Notice how similar it is to the Atom service document, with a “service” root element and “workspace” elements containing “collection” elements that outline the types of data available. In this case you see that there are Categories, CustomerDemographics, Customers, Employees and more available in this service.

In addition to the service document, an OData service also has a metadata document, a resource which describes the data in the OData service. The metadata document itself is available at a “well-known” URL, which is the service document URL with the value $metadata appended. For this Northwind OData service, this means that the metadata document should be available at:

https://services.odata.org/V3/Northwind/Northwind.svc/$metadata

Go to this URL and examine the first part of the metadata, which should look something like this:

Notice that the basic structure at the start of the metadata document describes the entity types and their properties. You should see entity type definitions for the Category entity type, the CustomerDemographics entity type, and more.

You should also see that the properties within these entities are described, that some are defined as key properties, and also some are defined as navigation properties, that describe a link from one entity type to another. For example, there is a relationship between the Category entity type and the Products entity type by means of the “Products” navigation property in the definition of the Category entity type.

If you’re interested, you can scroll through the metadata document to the Association definitions to find more details about this relationship identified by the ID FK_Products_Categories. You will find the definition of an association that looks like this:

and the definition of an association set that looks like this:

In the previous step you examined entity types. These are detailed descriptions of entities available in the OData service. The entities themselves are available in so-called entity sets. The relationship between entities and entity sets with OData is the direct equivalent of the relationship between entries and feeds in RSS and Atom. In fact, you’ll see that entry and feed elements live on in the OData format.

Entity sets have their own definitions in the metadata document, described by EntitySet elements within the EntityContainer element. Scroll down to find, or search for EntityContainer, and you will see within it a definition of all the entity sets available in this OData service. It will look something like this:

Notice there is an entity set “Products”, that is a set of entities of type “Product”. Search higher up in the metadata document for the entity type “Product”, and examine the definition, which should look something like this:

You can navigate directly to an entity set by appending its name onto the end of the service document URL. Do that now for the Products entity set, like this:

https://services.odata.org/V3/Northwind/Northwind.svc/Products

You will see the XML representation of the Products entity set. Unless you already have a browser feature to display XML prettily, it will look something like this:

It’s not easy to read like this, but you should be still able to discern, even in this rendering, features with which you’re now familiar. Notice the XML feed element is the root element, representing a collection of things. Notice also the first entry element, representing the start of the first product record in this collection.

The Chrome browser is recommended here, as it has a good choice of extensions that can make life easier. There are extensions for Chrome to render XML in a more human-friendly way. One of these extensions is XML Tree. There are others, but this one will do. Install this in your Chrome browser by following the instructions on the extension page and then reload the Products entity set resource. It should now look something like this:

Much easier to read, and clearly visible is the structure and relationship described by the feed and entry elements. It’s now also easier to see the actual product data - in this screenshot there is the Chai product, with 39 units in stock.

In the screenshot in the previous step, notice the link XML elements, in particular the ones with the title attribute values Category, Order_Details and Supplier. Notice also the corresponding values of their type attributes: entry, feed and entry respectively:

Re-examine the metadata document to work out what these might be. Look for the Product entity type definition, which (with the new XML Tree extension) will look something like this:

Look at the three navigation properties defined. They describe relationships between the Product entity type and the Category, Order_Details and Supplier entity types.

The relationship to the Category entity type is described with the ID NorthwindModel.FK_Products_Categories, with the To_Role attribute value being Categories. Search elsewhere in the metadata document for FK_Products_Categories to find the Association definition:

Notice that the value of the Multiplicity attribute for the Categories role is defined as “0..1”. This means that there can be either zero or one categories for a product. This is why when we follow the navigation property from a Product entity type to a Category entity type (see the screenshot at the start of this step) the type of the link element is entry, not feed.

Follow the same path for the relationship to the OrderDetails navigation property described with the To_Role attribute value of Order_Details, and you will find, via the relationship FK_Order_Details_Products, that the Association definition looks like this:

In this case, the value of the Multiplicity attribute described for this relationship is *. This means that there can be zero, one or more order details for a product. This is why when we follow this navigation property the type of the link element is feed, rather than entity.

The URL https://services.odata.org/V3/Northwind/Northwind.svc/Products shows the Products entity set, a feed of individual entries, each one representing a product. In each product entry element there is a child id element with the unique URL for that particular product, like in this example:

Specify that ID in the browser address bar, by adding (1) to the end of the existing URL:

https://services.odata.org/V3/Northwind/Northwind.svc/Products(1)

Note that the resource returned is the entry for that specific product.

To see how the navigation properties work, go from the individual property entry in the previous step to a list of the related order details. Remembering the navigation property concerned, Order_Details, add it to the end of the existing URL in the address bar to navigate to this URL: https://services.odata.org/V3/Northwind/Northwind.svc/Products(1)/Order_Details.

You should see that the resulting resource is a feed, a collection of entries representing the orders relating to the product specified.

Finally, use the OData system query option $count to retrieve the number of order details, rather than the order details themselves. Append $count onto the end of the existing URL like this:

https://services.odata.org/V3/Northwind/Northwind.svc/Products(1)/Order_Details/$count