To me, OData is simply the Broker API exposed as a web service – at least the most popular functionality of the original Broker API.  This is useful if your website is not .NET or Java based (PHP for instance), or if the app that needs to pull content across the internet or via AJAX, or for some other reason where database calls to the Broker are restricted.  In this tutorial I cover getting started with OData and also dive into some of the more advanced query string operations.
 

A common argument that architects make is that they don’t want to introduce dependencies on third party APIs.  In this case, I don’t buy it.  Just because you’re not including a third-party DLL or JAR file as part of your codebase, doesn’t mean you haven’t introduced dependencies.  You still need code that is specific to binding to the web service and working with its entities (e.g. proxy classes and the usual crap when working with any web service).  This is simply additional effort that we don’t have to expend by using the native API.

So if your website is running .NET or Java and can connect to the Broker Database, then using the native Broker API is probably a better idea.  It has been around longer, is a read-to-use object oriented set of classes, and offers advanced caching capabilities via the Tridion Object Cache and the Cache Channel Service.  Let’s keep the XPM (SiteEdit) integration as separate point of discussion, and Tridion 2013 actually addresses this.

If you are a .NETter, I urge you to put LINQ aside for a minute, or until you understand how to manually construct Tridion OData queries and the kind of result sets they return.  LINQ will not help you make them more efficient, since it automatically constructs them for you.  If you’re working with Java or PHP, then you’ll have no choice but to learn the fundamentals anyway.  So here we go…

Step 1 – Install It

So step 1 is installing the web service.  It is very easy.  Look at Nuno’s tutorial or read the official SDL documentation (login required).

Step 2 – Learn the Basics

The next step is to open up Firefox and type in some queries for your published content.  Remember, OData is a self-descriptive web service.  It’s very simple – just look at it.  

The place to start is by going to the root:

• On my IIS it’s on port 82 and my URL is this: http://localhost:82/odata.svc/
• On my Tomcat its on port 8080 and my URL is this: http://localhost:8080/cd_webservice/odata.svc

The above will list out all the entities that are available.  Here is what you should see:

Take any one of the entities, append to the URL and see what comes next.  For instance:

http://localhost:82/odata.svc/ComponentPresentations returns all the Dynamic Component Presentations (limited to the default max resultset specified in the cd_webservice_config.xml).

Inside the result you will see each of the published DCPs as <entry> nodes.  Take note of a special property called <link>.  It provides the relative URLs of the linked entities:

For instance, for each Component Presentation we can make a subsequent web service call to retrieve the linked Component, Template and Pages.

This covers the basics.

Step 3 – Advanced Functionality

It is important to be conscious about the number of web service calls our application is making and the impact to your application’s performance.  Each additional HTTP Request/Response is overhead.

$expand:

So how do we avoid having to make several calls to drill down into a DCP’s Component, Template or Pages?

The answer is $expand.  You can expand on any one given linked entity and keep expanding.  

Here is a simple example:
To get the Component Template of a given Component Presentation:
http://localhost:82/odata.svc/ComponentPresentations?$expand=Template

You’ll notice that an inline entry appears within the Component Presentation:

Here is another example:

To get all the ComponentPresentations associated with a Custom Meta, you need to get to it from CustomMetas, through the Component:  CustomMetas–>Component–>ComponentPresentations

http://localhost:82/odata.svc/CustomMetas?$filter=StringValue eq ‘Golf’&$expand=Component/ComponentPresentations

So now we can get what we need with less HTTP Requests – sweet!

$filter

The next important operation I want to discuss is $filter.  With this handy op you can filter by any property of an <entry>.  The query example above already utilizes it and filters on the “StringValue” property of a CustomMetas entry.  As Mihai pointed out in his post (http://yatb.mitza.net/2012/11/tridion-odata-whats-possible-and-what.html), you cannot easily query across multiple CustomMetas entries (actually you can, but that is a separate article).

There are other handy operations like “$top” and “$orderby”, as well as all kinds of operants like “eq”, “substringof” and so on.  For more operations and how to use them, refer to the OData Query String Operations documentation:  http://www.odata.org/documentation/uri-conventions#4_Query_String_Options

Publish DCPs with REL

OK, I lied, there are actually 4 important points that I wanted to cover, not 3.  The 4th one being Render Engine Language (REL).  It complements OData.  If your Dynamic Component Templates don’t use REL as the Output Format, you will have a lot more work on your hands.  You will need to handle each Dynamic Link individually by parsing it out from your rich text fields and by invoking the Linking Web Service API (login required): http://sdllivecontent.sdl.com/LiveContent/content/en-US/SDL_Tridion_2011_SPONE/reference_277A2D7264B04A39870C3FE18EF245BB.

With REL, all links appear resolved in your returned content, easy peasy.

Conclusion

Hopefully you find this tutorial insightful.  After learning the fundamentals behind OData’s features, go ahead and LINQ it up, Jaxb, Axis2, whatever.  Remember, if you need to debug a query, the easiest thing to do is to hit the browser with the URL and look at the response.