First looks at OpenSocial: part 1 (URLs)

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.

About David Megginson

Scholar, tech guy, Canuck, open-source/data/information zealot, urban pedestrian, language geek, tea drinker, pater familias, red tory, amateur musician, private pilot.
This entry was posted in Uncategorized and tagged , , . Bookmark the permalink.

4 Responses to First looks at OpenSocial: part 1 (URLs)

  1. Dave Pawson says:

    Thanks David. Look forward to the remainder of the ‘review’.

  2. Zack says:

    It seems like the activity URL should be:

    /feeds/people/{userId}/activities

    Are they really so inconsistent on ordering and on ‘people’ vs ‘users’? That’s not promising.

  3. Pingback: Megginson Technologies: Quoderat » Blog Archive » First looks at OpenSocial: part 2 (content for members and friends)

  4. Pingback: Megginson Technologies: Quoderat » Blog Archive » First looks at OpenSocial: part 3 (content for activities)

Comments are closed.