2008/05/13

XRDS-Simple (Yadis) + URI Templates

In writing up the OpenSocial 0.8 RESTful API spec, I ran up against a discovery gap. Clients know what social network container they want to query (e.g., orkut.com) and they know what kind of data they want to get (e.g., list of friends). An easy way to spec this is to mandate that every site has to support the same URI paths, like /friends/{userid}, and then just concatenate to get a final URI -- http://orkut.com/friends/{userid}. This turns out to be difficult in general; there are existing path conflicts, different server technologies make certain paths hard, etc. It turns out that you need to let containers provide different paths. So, there's a real discovery problem.

Enter XRDS-Simple (aka Yadis), the discovery mechanism used by OpenID and OAuth. It lets a client query the URI http://orkut.com to find out what URI to use to retrieve friends. Perfect!

Except, that /friends/{userid} isn't a URI -- it's a recipe, or template, for a URI. So XRDS-Simple can't actually technically hand that to you, because it only hands out URIs. It could hand you a list of every possible URI, starting with user aaab and ending with user zziee, but that's not too scalable.

So I invented the URI-Template parameter, which uses a URI Template:

<os:URI-Template>http://api.example.org/people/{guid}</os:URI-Template>

The idea is that the discovery document can use URI-Template wherever it could use URI, letting it specify an entire class of URIs in one fell swoop. Of course the client has to know about the template parameter names and how to use the endpoint, but that's the same no matter what: The clients have to know how to deal with the URIs once they have them, based on the spec. The template parameters are baked into the spec, the exact URI format isn't.

Note that this also means a site could outsource its API to an entirely different site. And if you have a personalized discovery document for a given user, you can still use concrete URIs and everything works as it does in normal XRDS discovery.

Updated at to clarify that the new thing is the URI-Template element, not URI templates in general.

4 comments:

  1. 1. Your XRDS-Simple is broken (missing the "h" in "http).

    2. You didn't invent URI templates. OpenSearch had them for a long time and their is a URI template draft RFC written by Joe Gregorio http://www.google.com/search?q=uri+templates

    ReplyDelete
  2. The OpenSocial RESTful API spec references Joe's URI Template RFC. The (minimal) 'invention' is using templates with XRDS files. Updated the post to clarify, and also to try to add back in the HTML markup which Blogger ate when I posted.

    ReplyDelete
  3. I am curious as to why you considered XRDS, as opposed to, let's say APP service documents. Any way, you are extending XRDS, but why not extend service documents?

    For the specific case of finding a URI to the friends collection of a user, why not just model it as link relationship from the user's profile?

    ReplyDelete
  4. @subbu: AtomPub service documents could be extended too, but they would need more extension, as they are designed only to catalog collections not general endpoints. They also would need templates.

    Linking from a personal profile (or a personal xrds document at a openid endpoint) is certainly possible and supported; but OpenSocial itself doesn't mandate personal profile pages.

    ReplyDelete

Suspended by the Baby Boss at Twitter

Well!  I'm now suspended from Twitter for stating that Elon's jet was in London recently.  (It was flying in the air to Qatar at the...