Learn about OData Fundamentals
- Where OData came from and why it’s designed the way it is
- What the standard OData operations are and how they relate to HTTP
- What the public Northwind OData service has to offer
- What OData service documents and metadata documents describe
- The basics of OData entity types, sets and relationships
OData is an open standard that is both a data format and a protocol for consuming and manipulating data in a uniform way. It’s ISO/IEC approved and managed by the OASIS organization.
OData has its origins in the world of weblogs and syndication, but now serves to power a great deal of the API and integration activities in typical SAP enterprise environments. This tutorial will help you understand OData from the ground up. By looking briefly at RSS and Atom, precursors of OData in some ways, you’ll understand and feel more comfortable with OData and its mechanisms.
This tutorial is based upon OData versions 2 and 3. With the advent of OData version 4, there are some differences, but none significant enough to distract from the purpose of this particular tutorial which is to give a simple overview of OData and its origins.
- Step 1
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:
The resulting RSS content of this resource should look something like this (reduced here for brevity):xmlCopy
<?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.
Which entity is used to provide a pointer to the actual blog post in each case?
- Step 2
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
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
entryelements. 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.
Within a workspace element in a service document, what is the XML element that is used to describe what collection of entries are available?
- Step 3
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
Employeesand more available in this service.
- Step 4
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
$metadataappended. For this Northwind OData service, this means that the metadata document should be available at:
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
Categoryentity type, the
CustomerDemographicsentity 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
Categoryentity type and the
Productsentity type by means of the “Products” navigation property in the definition of the
If you’re interested, you can scroll through the metadata document to the
Associationdefinitions 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:
Going back to the definition of the entity type "Category", what properties are defined as key?
- Step 5
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
feedelements live on in the OData format.
Entity sets have their own definitions in the metadata document, described by
EntitySetelements within the
EntityContainerelement. 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:
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
feedelement is the root element, representing a collection of things. Notice also the first
entryelement, representing the start of the first product record in this collection.
What is the title of the entity set depicted here?
- Step 6
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
entryelements. It’s now also easier to see the actual product data - in this screenshot there is the
Chaiproduct, with 39 units in stock.
- Step 7
In the screenshot in the previous step, notice the
linkXML elements, in particular the ones with the title attribute values
Supplier. Notice also the corresponding values of their type attributes:
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
Productentity type and the
The relationship to the
Categoryentity type is described with the ID
NorthwindModel.FK_Products_Categories, with the
To_Roleattribute value being
Categories. Search elsewhere in the metadata document for
FK_Products_Categoriesto find the
Notice that the value of the
Multiplicityattribute for the
Categoriesrole 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
Productentity type to a
Categoryentity type (see the screenshot at the start of this step) the type of the
Follow the same path for the relationship to the
OrderDetailsnavigation property described with the
To_Roleattribute value of
Order_Details, and you will find, via the relationship
FK_Order_Details_Products, that the
Associationdefinition 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
feed, rather than
- Step 8
The URL https://services.odata.org/V3/Northwind/Northwind.svc/Products shows the
Productsentity set, a feed of individual entries, each one representing a product. In each product
entryelement there is a child
idelement 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:
Note that the resource returned is the entry for that specific product.
What is the root element of the XML returned for this specific product?
- Step 9
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
$countonto the end of the existing URL like this:
How many order details are there for the specific product?