In a year or two, we’ll know whether the Google-lead OpenSocial initiative was a turning point in the social web or just a weak shot fired across Facebook’s bow. In the meantime, I think it’s worth taking some time to digest the API docs, which are still pretty rough.

I don’t know what I’m talking about…

Instead of reading and understanding everything first and then posting from a (virtual) podium, I’m going to try to work out my own understanding of the APIs right here on the web. That means that I’ll be asking questions that I’ll find the answers for later, that I’ll be making incorrect assumptions, and that I’ll be deferring hard stuff (like authorization/authentication) until I understand the basics. This is not, then, an OpenSocial primer by any stretch, since I don’t actually know what I’m talking about, but it might be useful as a snapshot of how a developer approaches a new API.

It’s the URLs, stupid

OpenSocial is designed so that any app can get information from any site as long as it has permission (I’ll figure out how that works later) — to accomplish that, it uses standard URL patterns on every site returning Atom entries and feeds. So after digging through a lot of crackerjack, I finally found the prize buried in the docs. Here are the URL patterns:

Information about a person

http://{DOMAIN}/feeds/people/{userId}

GET only.

List of a person’s friends

http://{DOMAIN}/feeds/people/{userId}/friends

GET only.

List of a person’s activities

(Wrong?) http://{DOMAIN}/activities/feeds/activities/user/{userId}

GET only

List of a person’s activities from a single source

(Wrong?) http://{DOMAIN}/activities/feeds/activities/user/{userId}/source/{sourceId}

GET, POST, PUT, DELETE

Application-global data

http://{DOMAIN}/feeds/apps/{appId}/persistence/global
http://{DOMAIN}/feeds/apps/{appId}/persistence/global/{partKey}

GET, POST, PUT, DELETE

Per-instance data

http://{DOMAIN}/feeds/apps/{appId}/persistence/{userId}/instance/{instanceId}/{partKey}

GET, POST, PUT, DELETE

Shared user data

http://{DOMAIN}/feeds/apps/{appID}/persistence/{userId}/shared/{partKey}

GET, POST, PUT, DELETE

Friends’ shared data

http://{DOMAIN}/feeds/apps/{appID}/persistence/{userId}/friends

GET, POST, PUT, DELETE

Did I miss anything?

Listing all the URLs together like this, instead of spreading them out over pages and pages of docs, is the best way to start with a REST API. For example, you can tell at a glance what what kind of information is available and what is and isn’t writable (you can’t add new friends for a user, but you can add a new activity). Sure, Javascript libraries, etc. are nice, but the class hierarchies can obscure how simple the underlying data actually is (or “are”, if you’ve studied Latin). You can also spot possible typos in the docs — for example, what are the odds that the activity URLs are really supposed to start with “/activities/feeds/” when everything else starts with “/feeds/”? It could be poor, inconsistent design, but I suspect cut-and-paste errors.

Next time: content

The next time I get around to looking at OpenSocial, I’ll try to figure out the formats — it shouldn’t be too hard, since they’re all Atom entries or feeds. Then I’ll get into messier stuff like auth/auth, and I may eventually try adding OpenSocial support to my OurAirports hobby site, though it doesn’t even support friends yet.