Open Data Protocol

Open Data Protocol (OData) is a data access protocol initially defined by Microsoft. Versions 1.0, 2.0, and 3.0 are released under the Microsoft Open Specification Promise. Version 4.0 is currently being standardized at OASIS.^[1]

The protocol was designed to provide standard CRUD access to a data source via a website. It is similar to JDBC and ODBC although OData is not limited to SQL databases.

Implementations

OData is the protocol recommended for the Open Government Data Initiative.^[2] It is the data API for Microsoft Azure. eBay ^[3] provides an OData API to their data. SAP NetWeaver Gateway^[4] provides OData access to SAP Business Suite and SAP Business Warehouse. OData client implementations include IBM WebSphere,^[5] Microsoft SharePoint 2010 and WCF Data Services^[6] and Windward Reports.^[7]

Architecture

OData is built on the AtomPub protocol and JSON where the Atom structure is the envelope that contains the data returned from each OData request. An OData request uses the REST model for all requests. Each REST command is a POST, GET, PUT, PATCH, or DELETE http request (mapping to CRUD) where the specifics of the command are in the url.

GET: Get a collection of entities (as a feed document) or a single entity(as an entry document).
POST: Create a new entity from an entry document.
PUT: Update an existing entity with an entry document.
PATCH: Update an existing entity with a partial entry document.
DELETE: Remove an entity.

Any platform that provides support for HTTP and XML is enough to form HTTP requests to interact with AtomPub. The OData specification defines how AtomPub is used to standardize a typed, resource-oriented CRUD interface for manipulating data sources.

Functionality

Fundamentally OData extends AtomPub with a data model for defining typed or untyped values on an entity (e.g. columns in a row) and adds a query language for getting just the entity and the data requested.

The following examples use the sample OData datasource located at http://services.odata.org/OData/OData.svc. This URI is the root URI for the data source offered via the OData protocol. All requests are extensions of this URI.

Metadata

OData provides full metadata of the datasource. With a $metadata query it is possible to see the full structure of the data available from a given OData service, as well as data types, relationships, etc.

The document returned from the OData $metadata operation is defined by the “Entity Data Model for Data Services Packaging Format” specification which is a small document that says it’s the Schema element under the Edmx and DataServices elements. That Schema element and everything inside it is the “Conceptual Schema Definition File Format” specification, normally called the “CSDL spec” (or Conceptual Schema Definition Language specification). CSDL defines Microsoft’s Entity Data Model (EDM), which is also the data model of OData. The CSDL specification describes how to interpret the result of the $metadata operation to see what kind of data is being exposed by the OData service.

Partial metadata for http://services.odata.org/OData/OData.svc/$metadata (duplicate element types removed):

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<edmx:Edmx Version="1.0" xmlns:edmx="http://schemas.microsoft.com/ado/2007/06/edmx">
    <edmx:DataServices xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" m:DataServiceVersion="2.0">
        <Schema Namespace="ODataDemo" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns="http://schemas.microsoft.com/ado/2007/05/edm">
            <EntityType Name="Product">
                <Key>
                    <PropertyRef Name="ID"/>
                </Key>
                <Property Name="ID" Type="Edm.Int32" Nullable="false"/>
...
                <NavigationProperty Name="Category" Relationship="ODataDemo.Product_Category_Category_Products" FromRole="Product_Category" ToRole="Category_Products"/>
                <NavigationProperty Name="Supplier" Relationship="ODataDemo.Product_Supplier_Supplier_Products" FromRole="Product_Supplier" ToRole="Supplier_Products"/>
            </EntityType>
            <EntityType Name="Category">
...            
            </EntityType>
            <EntityType Name="Supplier">
                <Property Name="Address" Type="ODataDemo.Address" Nullable="false"/>
...                
            </EntityType>
            <ComplexType Name="Address">
                <Property Name="Street" Type="Edm.String" Nullable="true"/>
...                
            </ComplexType>
            <Association Name="Product_Category_Category_Products">
                <End Role="Product_Category" Type="ODataDemo.Product" Multiplicity="*"/>
                <End Role="Category_Products" Type="ODataDemo.Category" Multiplicity="0..1"/>
            </Association>
...            
            <EntityContainer Name="DemoService" m:IsDefaultEntityContainer="true">
                <EntitySet Name="Products" EntityType="ODataDemo.Product"/>
                <EntitySet Name="Categories" EntityType="ODataDemo.Category"/>
                <EntitySet Name="Suppliers" EntityType="ODataDemo.Supplier"/>
                <AssociationSet Name="Products_Category_Categories" Association="ODataDemo.Product_Category_Category_Products">
                    <End Role="Product_Category" EntitySet="Products"/>
                    <End Role="Category_Products" EntitySet="Categories"/>
                </AssociationSet>
...                
                <FunctionImport Name="GetProductsByRating" EntitySet="Products" ReturnType="Collection(ODataDemo.Product)" m:HttpMethod="GET">
                    <Parameter Name="rating" Type="Edm.Int32" Mode="In"/>
                </FunctionImport>
            </EntityContainer>
        </Schema>
    </edmx:DataServices>
</edmx:Edmx>

CSDL defines the usual primitive types which are the same types found in .NET DbTypes enum.

CSDL defines a Navigation element references a corresponding Association, which defines the nature of the relationship between two entity types. In most cases, the important part is the multiplicity defined on both ends.

To get to the related products, follow the relative URL in the href to a feed document which can have any number of products in it.

The properties in the content element map to properties on the entity type and what types each of the properties is. If it’s not specified, the default type is Edm.String.

Read

OData provides functionality to form URLs based on what you know (and can discover) about the underlying data. For example, you can start at the top level service document and keep drilling in.

A very simple query is http://services.odata.org/OData/OData.svc/Categories(0) which returns the first Category in the data source:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<entry xml:base="http://services.odata.org/OData/OData.svc/" 
   xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
   xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns="http://www.w3.org/2005/Atom">
  <id>http://services.odata.org/OData/OData.svc/Categories(0)</id>
  <title type="text">Food</title>
  <updated>2012-08-26T16:38:13Z</updated>
  <author>
    <name />
  </author>
  <link rel="edit" title="Category" href="Categories(0)" />
  <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Products" 
      type="application/atom+xml;type=feed" 
      title="Products" href="Categories(0)/Products" />
  <category term="ODataDemo.Category" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
  <content type="application/xml">
    <m:properties>
      <d:ID m:type="Edm.Int32">0</d:ID>
      <d:Name>Food</d:Name>
    </m:properties>
  </content>
</entry>

You can do more than request a single dataset. You can request more (multiple datasets), less (a single value), and links to associated data.

Client libraries

There are a number of OData client libraries available to access OData:

Microsoft .NET Framework 3.51: the WCF Data Services framework is available as a separate download for .NET 3.x.
Microsoft .NET Framework 4.0: the WCF Data Services framework built into .NET 4.0.
Java: odata4j (including Java on an Android phone) supports the OData protocol.
Java: Apache Olingo (Incubator) is a client and server library.
JavaScript: datajs XMLHttpRequest object is standard in modern browsers.
JavaScript: JayData for higher level of abstraction (LINQ-like syntax, support for OData geo features, IndexedDB, WebSQL, integration for Kendo UI, Angular.js, Knockout.js and Sencha).
JavaScript (Node.js): JayData for node
PHP: odataphp provides OData support for PHP clients.
AJAX: the ASP.NET Ajax Library for getting to OData.
Windward provides OData connection via Microsoft Office templates in either Java or .NET
Reporting tool List & Label has a specialized data provider for OData.

More libraries are listed at the OData.org site.

Blackberry (C++): OData-BB10 Open Data Protocol (OData) library for BlackBerry 10 (BB10) Cascades apps
Ruby: ruby_odata library

Server libraries

There are a number of OData server libraries available to publish OData:

Microsoft .NET Framework 3.5.1: the WCF Data Services framework is available as a separate download for .NET 3.x.
Microsoft .NET Framework 4.0: the WCF Data Services framework built into .NET 4.0.
Java: odata4j (including Java on an Android phone) supports the OData protocol.
Java: Apache Olingo (Incubator) is a client and server library.