For example, an HTML document is served up with a media type of text/html, but the actual information in the page is a person’s contact information marked up using hCard. An application interested in utilizing that contact information has no way of knowing whether or not the page contains that data without resorting to parsing it.

We say we want layered formats, because that’s what the combination of IETF IDs, W3C Recommendations and deployed browsers and servers allow us to say. It’s the Web version of of the Blub paradox. What we want is layered data. What we want is not just to qualify a media type, but to describe the ingredients in the entity whose “shell” is the media type.

I’d suggest that if you arrive at this point, it may indicate you’ve picked the wrong “shell.” Maybe I’m too dismissive, but I think there will always exist an impedance mismatch when attempting to define nested schemas for formats not suited to the purpose. The fact that we’ve reached a certain level of maturity with regard to extensibility (a huge engineering boon) is an exacerbating factor.

Before I get criticized for this viewpoint, I want to note explicitly that I am a proponent of microformats. I think they are incredible, and the enabling potential they offer to future browser extensions is well worth the effort in defining and developing them.

However, I believe this propensity towards nesting is ill-suited for scenarious involving structured data, often implying machine-to-machine communication. Any inadequecies inherent in media types can be easily overcome: simply define more formats that don’t necessitate deeper nesting. As a bonus, this fully complies with the REST architectural constraints.

In the address book example, HTML pages with microformats can continue to be delivered to people surfing via browsers. However, applications that are interested in structured data can request the same information be returned, not as HTML, but as vCard, a format designed specifically for the purpose of storing contact information, and delivered with a media type of text/x-vcard.

Nesting information in Atom (or RSS), while not obviating the media type issue, does not pose nearly the same problems. The reason is because Atom has a clear purpose as a container format, namely carrying a feed of items, such as news articles, that are generated over time. In contrast to the generic document markup of HTML, there are already constraints in place that should serve as guides when deciding whether or not Atom is an appropriate container.

Upon first seeing the spec, I immediately tweeted:

oEmbed completely ignores REST principles. GET with a Content-Type to the original resource. Benefit: a single URL per resource. C’mon!

Allow me to further explain…

To begin with, let’s dive into the specification, and take note of the things that immediately raise red flags.

An oEmbed exchange occurs between a consumer and a provider. A consumer wishes to show an embedded representation of a third party resource on their own web site, such as a photo or an embedded video. A provider implements the oEmbed API to allow consumers to fetch that representation.

Hmm… that sounds suspiciously like an HTTP GET request. Why the need to refer to this as “the oEmbed API”?!? Something suspect must be about to go down.

Configuration for oEmbed is very simple. Providers must specify one or more URL scheme and API endpoint pairs. The URL scheme describes which URLs provided by the service may have an embedded representation. The API endpoint describes where the consumer may request representations for those URLs.

Wait… what? This oEmbed thing requires two URLs to fetch different representations of the same resource? Have we not learned even the most rudimentary REST principles in the past few years? Here’s a quick lesson: a single resource can have multiple representations. One URL, multiple data formats. Once that is understood, the need for an oEmbed API endpoint drops away entirely.

Even so, let’s be pragmatic and use oEmbed, since some respectable providers have already implemented support for it. (Which begs further questions, but I’ll let that slide.) To start, we need to get the address of the API endpoint. That mechanism is not specified, so we’ll have to resort to hardcoding endpoints. XRDS could be useful here, but that introduces further complications. Besides, there is better way.

oEmbed with REST to the Rescue!

Since the URL to the original resource must be known, and an oEmbed representation is desired, the oEmbed API endpoint is completely unnecessary. Just request the oEmbed representation from the resource directly.

GET /photos/bees/2362225867/ HTTP/1.1
Host: flickr.com
Accept: application/oembed+xml


Flickr could then respond with our embed-ready resource.

HTTP/1.x 200 OK
Content-Type: application/oembed+xml
 
<oembed>
<version>1.0</version>
<type>photo</type>
<title>Bacon Lollys</title>
<author_name>bees</author_name>
<author_url>http://www.flickr.com/photos/bees/</author_url>
<cache_age>3600</cache_age>
<provider_name>Flickr</provider_name>
<provider_url>http://www.flickr.com/</provider_url>
<width>500</width>
<height>375</height>
<url>http://farm4.static.flickr.com/3040/2362225867_4a87ab8baf.jpg</url>
</oembed>


See that! There is absolutely zero requirement for the oEmbed API. All we need to do is define a couple data formats and the associated MIME types. While there is evidence of duplicative effort, the oEmbed formats look reasonable and have both XML and JSON output. I propose we define them as application/oembed+xml and application/oembed+json.

Error handling is equally trivial. If support for RESTful oEmbed is not implemented, a standard HTTP 406 Not Acceptable status code would be returned to the client. The client could then fail over to screen scraping or proprietary APIs as necessary.

I hope I’ve outlined my case against oEmbed effectively. If anyone has any questions or concerns, drop a line in the comments.

Ruby on Rails dramatically altered the way people build web applications. With the 1.2 release, it continues to influence thought patterns by bringing REST to the forefront. REST provides a set of principles for the design of network-based software. By presenting these patterns to a mainstream audience, Rails is having a profound impact on the future of software development.

The release also has numerous other improvements, including Unicode support, a new URL routing implementation, and better module loading.