Content Delivery Web Service (OData) Fundamentals – It’s as easy as 1-2-3!

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:

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.

3 thoughts on “Content Delivery Web Service (OData) Fundamentals – It’s as easy as 1-2-3!

  1. Great Post Nick !!
    Thanks for sharing the OData Fundamentals. A useful article for a beginner..

  2. Hi Nick, Performance wise which one is better odata or content delivery api. I am working on a .net application and can connect easily either to broker db or odata service but in the post you have implicitly mentioned that odata do not use cache. I believe internally odata is also using content api or is it directly talking to db?

  3. OData does cache the results, but they are on the OData server and you still have to make an HTTP connection and the round trip of the odata xml/json markup from the webservice server to your consuming application. On the other hand, the Content Delivery (Broker) API has an Object cache which is directly in memory of your consuming web application – no HTTP connection, no network latency. So off the bat, CD API after caching is faster. With this in mind, you can make OData just as fast as the CD API by caching the results on the consuming application using MemCache (for .NET) or ECache (Java). But this could be more work. The other thing to consider is licensing… Using CD API each developer will need a Tridion dev license to run the app locally. With OData you don’t have this constraint.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>