REST, OData and Atom

Introduction

Before I dive into other posts that explain what OData is and how to use it, I wanted to give a little background on what REST Designs are exactly as well as the Atom protocol. This protocol standard is the XML format which OData relies on to expose it’s data.

REST Designs

So many hear about it, but what does RESTFul mean and why is it getting so much attention? REST itself is a software architectural design. It is not a protocol, nor is it actually a standard (yet!). RESTFul services at their core, if done correctly, provide a way to expose data through an HTTP API (or WebAPI if you prefer) in such a way that, with little documentation, a client can use the exposed API to access data, update data and create data. This data is exposed using HTTP GET, PUT, POST and DELETE. The technique behind this design is the use of different types of XML or JSON formatted queries and responses. WebAPI ( a RESTFul design) uses JSON or straight XML, while OData (Data Services) uses a more Atom syntax. In a sense, there are similarities to SOAP in that it uses an XML type format, except SOAP has much more information required to function due to its contract nature and acts more as an envelope to serialize the data. That is about where the similarities end. SOAP is contract based and must be “consumed” in order to access its data.

OData has many conceptual similarities to the RESTFuL design pattern, but the architecture is not exactly the same. The first difference is that OData is a protocol standard and RESTFuL itself is an architectural design pattern. In saying this, OData exposes its protocol data in a REST way. The best way I can explain it is that OData sends data in a REST type implementation, but because OData itself is a protocol / standard, it only sends a specific type thus cannot be considered RESTFul. Another difference is the way in which the data is exposed via HTTP. They both expose data through the same generic method (HTTP), but the RESTFuL design pattern does things a little differently.

ATOM (Read)

Atom like all the XML formats is standard representation of data designed and approved by the W3C. If you don’t know, W3C is a committee that assists in forming the World Wide Web standards. Atom is also known as Atom Syndication Format (RFC 4287) and exposes what are known as ‘feeds’. Atom is the primary way in which standards like OData expose the data to be readable. This internet standard was originally used by bloggers to keep their subscribers up to date on their latest entries. It is this reason that an atom “feed” contains “entry” tags and is a required element within a particular Atom.

Take the following for example:

<?xml version="1.0" encoding="utf-8"?> 
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Awesome Company</title> 
  <link href="http://awesome.org/"/>
  <updated>2012-1-13T18:30:02Z</updated>
  <author> 
    <name>Gregg The man</name>
  </author> 
  <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id>
  <entry>
    <title>What is SOAP?</title>
    <link href="http://aweome.org/2013/1/13/atom03"/>
    <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
    <updated>2003-12-13T18:30:02Z</updated>
    <summary>Awesome information you must know.</summary>
<content type="application/xml">
      <m:properties>
        <d:CategoryID m:type="Edm.Int32">1</d:CategoryID> 
        <d:CategoryName>C# Tips</d:CategoryName> 
        <d:Description>async is the bees neez</d:Description> 
        <d:Picture m:type="Edm.Binary">FRwvAAX#@!$fdsfswe</d:Picture> 
    </m:properties>
    </content>
  </entry>
</feed>

As you can see above, There are several fields that indicate to the subscriber (usually an Atom Feeder) when the last update was, and various information about this particular update. Usually, the updated element is checked over and over by the feeder to check for new information based on the last pull.

AtomPub (Update)

AtomPub, also known as Atom Publishing Protocol, is a set of services used to expose “collections” of elements / entities / entries as well as allow a client application the ability to create, update and delete these items. AtomPub uses Service as the first element instead of Feed and workspace instead of entry, otherwise the format is the same. When doing any CRUD type operations, HTTP GET, PUT, POST and DELETE are used to alter and get data from the exposed API.

See below for an example of an AtomPub POST (create a new category)

POST /owind.svc/Categories/ HTTP/1.1
Accept: application/atom+xml
Content-Type: application/atom+xml;type=entry
Host: localhost:8080
Content-Length: 632
Expect: 100-continue
Connection: Keep-Alive

<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <title>A new Awesome category</title>
  <id>urn:uuid:25ab211e-cb1e-436b-b3c0-54ad960cff4d</id>
  <updated>2013-12-25T22:04:28.2682406-08:00</updated>
  <author><name>C# is awesome, VB stinks</name></author>
  <content type="application/xml">
    <properties
      xmlns="http://schemas.microsoft.com/ado/2013/12/dataservices/metadata">
      <CategoryName
xmlns="http://schemas.microsoft.com/ado/20013/12/dataservices">Programing</CategoryName>
      <Description
        xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices">Everything C# there is to know</Description>
    </properties>
  </content>
</entry>

This concludes the background information. Next article, we will be diving into the C# code using OData via WCF Data Services.

Continue To Next Article…

References

http://programmers.stackexchange.com/questions/114690/how-is-odata-different-from-a-rest-service

http://www.eidias.com/Blog/2012/4/2/practical-differences-between-aspnet-web-api-and-wcf-data-services

Happy Coding!