Skip to main content

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.

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

Post a Comment

Popular posts from this blog

The problem with creation date metadata in PDF documents

Last night Rachel Maddow talked about an apparently fake NSA document "leaked" to her organization.  There's a lot of info there, I suggest you listen to the whole thing:

http://www.msnbc.com/rachel-maddow/watch/maddow-to-news-orgs-heads-up-for-hoaxes-985491523709

There's a lot to unpack there but it looks like somebody tried to fool MSNBC into running with a fake accusation based on faked NSA documents, apparently based on cloning the document the Intercept published back on 6/5/2017, which to all appearances was itself a real NSA document in PDF form.

I think the main thrust of this story is chilling and really important to get straight -- some person or persons unknown is sending forged PDFs to news organization(s), apparently trying to get them to run stories based on forged documents.  And I completely agree with Maddow that she was right to send up a "signal flare" to all the news organizations to look out for forgeries.  Really, really, really import…

Personal Web Discovery (aka Webfinger)

There's a particular discovery problem for open and distributed protocols such as OpenID, OAuth, Portable Contacts, Activity Streams, and OpenSocial.  It seems like a trivial problem, but it's one of the stumbling blocks that slows mass adoption.  We need to fix it.  So first, I'm going to name it:

The Personal Web Discovery Problem:  Given a person, how do I find out what services that person uses?
This does sound trivial, doesn't it?  And it is easy as long as you're service-centric; if you're building on top of social network X, there is no discovery problem, or at least only a trivial one that can be solved with proprietary APIs.  But what if you want to build on top of X,Y, and Z?  Well, you write code to make the user log in to each one so you can call those proprietary APIs... which means the user has to tell you their identity (and probably password) on each one... and the user has already clicked the Back button because this is complicated and annoying.

My faxed letter to both my Senators this morning

My faxed letter to both my Senators this morning.

Senators Grassley and Graham, this morning, engaged in an obvious act of witness intimidation. They leaked a letter to the Justice Department referring criminal prosecution against Mr. Steele for alleged but unspecified false statements to, apparently, the FBI.

This is on the heels of Senator Grassley refusing to release the testimony of Fusion GPS, refusing to allow the public to evaluate the claims of Simpson vs. selective and apparently inaccurate leaks of said information from the Republican members of the committee.

This is outrageous.

It is unacceptable. It is un-American. These Senators are trying to achieve in then court of public opinion what they have no chance of doing in a real court. They are themselves engaging in witness intimidation & obstruction of justice.

I call on you to denounce this desperate and illegal act by your colleagues and to introduce a motion to censure these two sitting Senators who have demeaned th…