Five Minutes on OAuth + OpenSocial RESTful APIs

MySpace using OpenSocial RESTful API

Announced on TechCrunch, and they have a sample app (developed between 9am and 5pm today). Cool! It's using the OpenSocial 0.8 RESTful People API, with OAuth Core.

OpenSocial RESTful is popping up everywhere

Go Hi5!

curl http://sandbox.hi5.com/social/rest/people/1000/@friends

...and Dan Bentley had a very nice demo showing how to use the RESTful API within an App Engine app to add social features outside of a gadget.

OpenSocial RESTful API

For those who were at the OpenSocial summit yesterday, here are the slides from my RESTful API talk:



In a nutshell, the OpenSocial RESTful API is a catalyst that enables participation in a much larger and more complex ecosystem.

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.

new OpenSocialFoundation(); new APIs();

It's been a busy few days. The OpenSocial Foundation sprang into being on Tuesday, with MySpace, Yahoo!, Google, and Hi5 as initial members; on the same day, Microsoft announced contact portability for its Windows Live Contacts service, partnering with Facebook, Bebo, Hi5, Tagged, and LinkedIn to access and re-use contact data. (We announced the Google Data Contacts API on March 5.) Seems like there's a trend here!

On a somewhat related note, we're moving forward on the OpenSocial RESTful API.

Update 3/31: Hi5 too!