OpenSocial REST Developer's Guide (v0.9)

Owned by Mark Halvorson (Deactivated)
Last updated: Nov 16, 2010 by Jonathan Beri (Unlicensed)Version comment
14 min read

The OpenSocial REST API allows client applications to view and publish users' OpenSocial data.
Your client application can use the OpenSocial REST API to request data items (such as Activity, Person, or AppData items), create new items, edit or delete existing items, and filter or modify results using query parameters.
In addition to providing some background on the capabilities of the OpenSocial REST API, this document provides examples of basic REST API interactions using HTTP and JSON.
This document does not cover the RPC protocol.

Audience

This document is intended for programmers who want to write client applications, using HTTP and JSON, that can interact with social networks that provide OpenSocial data.
This document assumes that you understand the general idea of a REST API, and that you're familiar with the GUI of the social network you're working with.
This document is very general; it tries to cover the REST API in general rather than any particular social network site. The social network your application interacts with may provide its own more specific documentation.
If you're using a UNIX system and you want to try the examples in this document without writing any code, you may find the UNIX command-line utilities curl or wget useful; for more information, see the manual pages for those utilities.

Getting started

Creating a user account

You may want to sign up for a user account with an appropriate OpenSocial social network for testing purposes.

About data formats

Data provided by the REST API takes the form of an item or collection of items. Items can be represented in various formats; in particular, OpenSocial collections can take the form of JSON objects, Atom feeds, or non-Atom XML data.
This document focuses on JSON, but if you want to use Atom or non-Atom XML instead (and the social network you're working with supports those formats), then everything works the same way; the data just appears in a different format.

About OpenSocial data types

The REST API provides three types of data items:
Person
Information about a person. A collection of these items represents a group of people, such as a given user's friends.
Activity
Information about an activity performed by a user within the social network. A collection of these items represents an activity stream—a list of the activities the user has performed.
AppData
An item of data, such as a preference setting, stored by the social network on a user's behalf for a given application. A collection of these items might be the whole set of preferences for the application.
For more information about these data types, see the appropriate sections of this developer's guide.

Authenticating with OAuth

You can access both public and private data using the OpenSocial REST API. Public collections don't require any authentication, but they are read-only. If you want to modify items or read private collections, then your client needs to authenticate first, using OAuth, and then provide credentials with requests. Every request for private data must be accompanied by OAuth authentication parameters.
OAuth is an open standard authentication protocol that allows applications to make authorized and authenticated API calls. With OAuth, your application doesn't need access to the user's username and password; instead, the application obtains obtains an authentication token from the social network site that your application can use to act on the user's behalf.
Most of the samples in subsequent sections of this document assume you're supplying the appropriate authentication, if needed.
When a user first visits your application, they have not yet been authenticated. To authenticate them, your application performs the following general steps:

  1. Send a request to the social network site to acquire a generic OAuth "request token."
  2. Send the user to the social network's authorization page so that they can authorize your request for access. After the user authorizes the request, the social network sends the user back to your client, using a URL that you specify. The request token that you acquired in step 1 is now authorized.
  3. Send a request to the social network site to upgrade the authorized request token to an access token.
  4. Store the access token securely, for future use.
  5. Use the access token to perform actions on the user's behalf.
    For more detailed information, see the OAuth Getting Started guide.
    For an example of using OAuth, see Appendix A of the OAuth Core specification.

Discovering URLs

This document contains example URLs, but these examples are not guaranteed to work with all social networks.
Requests to the REST protocol follow this general format:

HTTPVerb http://baseURL/serviceName/userID/selector?queryParameters

For example:

GET http://api.example.org/people/userID/@friends?sortBy=updated

However, the specific formats of the URLs for a given social network are determined, and published, by the social network site.
To find out what the URL formats are for a given social network, obtain the social network's discovery document.
You can write your client in such a way that it obtains the discovery document each time it needs to perform a REST API operation; but it may be simpler to obtain the discovery document once, manually, while writing your client, and then specify the social network's actual URLs in your client.
The discovery document is an XML file in XRDS, the same format used for OpenID and OAuth discovery. It declares what features the social network supports, and provides URL templates that a client can use to determine how to request a resource from the social network.
To locate the discovery document, send an HTTP GET request to the social network's main URI (such as http://example.org/), with an Accept header set to application/xrds+xml.
The social network returns either an X-XRDS-Location header pointing to the discovery document, or the document itself.
Here's an example of a discovery document:

<XRDS xmlns="xri://$xrds">
  <XRD xmlns:simple="http://xrds-simple.net/core/1.0" xmlns="xri://$XRD*($v*2.0)"
      xmlns:os="http://ns.opensocial.org/2008/opensocial" version="2.0">
    <Type>xri://$xrds*simple</Type>
    <Service>
      <Type>http://ns.opensocial.org/2008/opensocial/people</Type>
      <os:URI-Template>http://api.example.org/people/{guid}/{selector}{-prefix|/|pid}</os:URI-Template>
    </Service>
    <Service>
      <Type>http://ns.opensocial.org/2008/opensocial/groups</Type>
      <os:URI-Template>http://api.example.org/groups/{guid}</os:URI-Template>
    </Service>
    <Service>
      <Type>http://ns.opensocial.org/2008/opensocial/activities</Type>
      <os:URI-Template>http://api.example.org/activities/{guid}/{appid}/{selector}</os:URI-Template>
    </Service>
    <Service>
      <Type>http://ns.opensocial.org//2008/opensocial/appdata</Type>
      <os:URI-Template>http://api.example.org/appdata/{guid}/{appid}/{selector}</os:URI-Template>
    </Service>
    <Service>
      <Type>http://ns.opensocial.org//2008/opensocial/messages</Type>
      <os:URI-Template>http://api.example.org/messages/{guid}/{selector}</os:URI-Template>
    </Service>
  </XRD>
</XRDS>

To find a specific resource, instantiate one of the URL templates by replacing the items in braces. For example, given the above discovery document, you might use the following URL to obtain a list of activities:

http://api.example.org/activities/1000/

(Where 1000 is a user ID for that social network.)
The templates use standard URI Template syntax. For details about the placeholder names, such as guid, appid, and selector, see the OpenSocial REST API specification.

Managing user profile information

After authenticating, you can retrieve profile information about users.
A Person item, also called a Person, contains a person's profile information.
A Person collection lists the people relevant to the specified user.

Retrieving user information

The following sections describe how to retrieve user information, with and without query parameters.
You can query a public collection without authentication. Therefore, you don't need to set the Authorization parameter when you retrieve data from a public Person collection.

Retrieving a specific user's profile information

To retrieve a user's profile information, send an authenticated HTTP GET request to the following URL:

http://api.example.org/people/userID/@self

Replace userID with any user's ID.
Note: For most social networks, to obtain a user ID you'll need to first send an authenticated request that uses @me for the user ID, which tells the social network to return the profile information for the user whose credentials accompany the request.
On receiving the request, the social network returns the user's profile information. It might look something like this:

{
  "entry" : {
    "id" : "example.org:34KJDCSKJN2HHF0DW20394",
    "displayName" : "Liz",
    "name" : {"unstructured" : "Elizabeth Bennet"},
    "gender" : "female"
  }
}

Retrieving a user's contacts

You can retrieve a list of a user's friends, or a list of all of their contacts, by changing the "selector" at the end of the URL.
To retrieve a list of a user's friends, send a GET request to the following URL:

http://api.example.org/people/userID/@friends

To retrieve a list of all of a user's contacts, send a GET request to the following URL:

http://api.example.org/people/userID/@all

Replace userID with any user's ID, or with @me to request the authenticated user's friends or contacts.
In place of @friends or @all, you can specify a specific group ID to request user information about all of the people in a particular group. For example, a user might have defined a group named dancers that contains some of their contacts; your code could specify that group ID to retrieve a list of the members of that group.
In response to any of these requests, the social network returns an HTTP 200 OK status code and a collection containing user information in JSON format, one item for each member of the requested group. For example, if the user has only one friend, the friends collection might look like the following:

{
  "startIndex": 0,
  "totalResults": 1,
  "entry": [
    {
      "id": "example.org:17MXBCSKJN2OZF0DW20916",
      "name":
        {
          "familyName": "Bennet",
          "givenName": "Jane"
        }
    }
  ]
}

For information about what each of those attributes means, see the OpenSocial REST API specification.
If your request fails for some reason, the social network may return a different status code. For information about HTTP status codes, see the status codes section of the REST API specification.

Filtering, sorting, and paginating lists of people

The OpenSocial REST API lets you specify various criteria to apply to the returned collection, such as requesting that the items be sorted in a particular order, or requesting that only a particular set of fields be returned for each Person in the collection.
For example, to request that the returned items be ordered by last-updated date, add the sortBy parameter to the request URL:

GET http://api.example.org/people/userID/selector?sortBy=updated

When you send that GET request, the social network returns an HTTP 200 OK status code and a collection of people sorted by date.
Another example: if you want to break up your request to ensure that you only retrieve a limited number of people at a time (such as ten people per "page" of results), you can use the count and startIndex query parameters to retrieve a list of people one page at a time.
For more information about the supported query parameters, see Query parameter reference.

Creating, updating, and deleting profile information

The OpenSocial REST protocol allows for social networks to support creating, updating, and deleting Person items using the POST, PUT, and DELETE HTTP verbs (respectively). However, most social networks don't support those actions, so this guide doesn't cover them.
Managing Activity items

After authenticating, you can publish and retrieve Activity items.
An Activity contains information about an activity performed by the user within the social network.
An Activity collection lists the Activity items relevant to the user.

Creating Activity items

First, create a JSON representation of the Activity to publish. The JSON might look like this:

{
  "title" : { "type" : "html",
              "value" : "<a href=\"foo\">Dancing with Darcy</a>"
            }
  "updated" : "2008-02-20T23:35:37.266Z",
  "body" : "Attending a dance at the Pavilion with Darcy.",
  "bodyId" : "383777272"
  "url" : "http://api.example.org/activity/feeds/.../af3778"
  "userId" : "example.org:34KJDCSKJN2HHF0DW20394"
}

To publish this entry, send it to the Activity items URL as follows:

  1. Place your JSON code in the body of a new POST request, using the application/json content type.
  2. Instantiate the Activity items URL, using the URL template specified in the discovery document.
  3. Post the request to the URL, with appropriate authentication.
    The social network creates an Activity using the entry you sent, then returns an HTTP 201 Created status code, along with a copy of the new Activity. The Activity returned is the same one you sent, but it also contains some information generated and added by the social network.
    If your request fails for some reason, the social network may return a different status code. For information about HTTP status codes, see the REST API specification.

Retrieving Activity items

The following two sections describe how to retrieve a collection of Activity items, with and without query parameters.
You can query a public collection without authentication. Therefore, you don't need to set the Authorization parameter when you retrieve Activity items from a public Activity stream.

Retrieving all Activity items

To retrieve the user's Activity items, send an HTTP GET request to the Activity URL. The social network returns a collection of the appropriate Activity items. For example, to get a list of Activity items for a given user, send the following HTTP request to the social network (with the appropriate value in place of userID, of course):

GET http://api.example.org/activities/userID/appID/selector

Note: In an authenticated request, you can substitute @me for the user ID, which tells the social network to return the collection of Activity items for the user whose credentials accompany the request.
The selector can be any of the following:
@self
The user's activities.
@friends
All of the activities from all of the user's friends.
@all
All of the activities from all of the user's contacts.
groupID
All of the activities from everyone in the specified group.
@self/activityID
A specific activity item for the specified user. (Usually your client acquires the ID of a particular activity item by examining the full @self collection.)
The social network then returns an HTTP 200 OK status code and a collection containing the Activity items, in JSON format.
The following is an example of an Activity items collection that contains only one Activity.

{
  "author" : "example.org:58UIDCSIOP233FDKK3HD44",
  "link" : {"rel" : "next", "href" : "http://api.example.org/..." },
  "totalResults" : 100,
  "startIndex" : 1
  "itemsPerPage" : 10
  "entry" : [
    {
      "id" : "http://example.org/activities/example.org:87ead8dead6beef/self/af3778",
      "title" : { "type" : "html",
                  "value" : "<a href=\"foo\">some activity</a>"
                }
      "updated" : "2008-02-20T23:35:37.266Z",
      "body" : "Some details for some activity",
      "bodyId" : "383777272"
      "url" : "http://api.example.org/activity/feeds/.../af3778"
      "userId" : "example.org:34KJDCSKJN2HHF0DW20394"
    }
  ]
}

For information about what each of those attributes means, see the OpenSocial REST API specification.
If your request fails for some reason, the social network may return a different status code. For information about HTTP status codes, see the REST API specification.

Filtering, sorting, and paginating Activity items

The OpenSocial REST API lets you specify various criteria to apply to the returned collection, such as requesting that the items be sorted in a particular order, or requesting that only a particular set of fields be returned for each Activity in the collection.
For example, to request that Activity items be ordered by last-updated date, add the orderby parameter to the request URL:

GET http://api.example.org/activities/userID?orderby=updated

When you send that GET request, the social network returns an HTTP 200 OK status code and a collection of Activity items sorted by date.
For more information about the supported query parameters, see Query parameter reference.

Updating and deleting Activity items

The OpenSocial REST protocol allows for social networks to support updating and deleting Activity items using the PUT and DELETE HTTP verbs (respectively). However, most social networks don't support those actions, so this guide doesn't cover them.

Managing AppData items

After authenticating, you can publish and retrieve AppData items.
An AppData item is an item of data, such as a preference setting, stored by the social network site on the user's behalf.
An AppData collection lists the AppData items relevant to the user.

Creating AppData items

First, create a JSON representation of the AppData item to publish. The JSON might look like this:

{
  "example.org:34KJDCSKJN2HHF0DW20394" : {"pokes" : 3, "last_poke" : "2008-02-13T18:30:02Z" }
}

To publish this entry, send it to the AppData items URL as follows:

  1. Place your JSON code in the body of a new POST request, using the application/json content type.
  2. Instantiate the AppData items URL, using the URL template specified in the discovery document.
  3. Post the request to the URL, with appropriate authentication.
    The social network creates an AppData item using the entry you sent, then returns an HTTP 201 Created status code, along with a copy of the new AppData item. The AppData item returned is the same one you sent, but it also contains some information generated and added by the social network.
    If your request fails for some reason, the social network may return a different status code. For information about HTTP status codes, see the REST API specification.

Retrieving AppData items

The following two sections describe how to retrieve a collection of AppData items, with and without query parameters.
You can query a public collection without authentication. Therefore, you don't need to set the Authorization parameter when you retrieve AppData items from a public application data stream.

Retrieving all AppData items

To retrieve the user's AppData items, send an HTTP GET request to the AppData item URL. The social network returns a collection of the appropriate AppData items. For example, to get a list of your application's AppData items for a given user, send the following HTTP request to the social network (with the appropriate value in place of userID, of course):

GET http://api.example.org/appdata/userID/appID/selector

Note: In an authenticated request, you can substitute @me for the user ID, which tells the social network to return the collection of AppData items for the user whose credentials accompany the request.
The selector can be any of the following:
@self
The user's application data.
@friends
All of the application data from all of the user's friends.
@all
All of the application data from all of the user's contacts.
groupID
All of the application data from everyone in the specified group.

The social network then returns an HTTP 200 OK status code and a collection containing the AppData items, in JSON format.
The following is an example of an AppData items collection for a user's friends.

{
  "entry": {
    "10459228050876679741": {
      "letters": "2",
      "last_letter_date": "2008-10-15T10:01:00Z"
    },
    "07365476160138082838": {
      "letters": "1",
      "last_letter_date": "2008-09-28T08:20:20Z"
    }
  }
}

Note that a single AppData entry object can contain AppData for multiple users, and there can be multiple pieces of data for each user.
If your request fails for some reason, the social network may return a different status code. For information about HTTP status codes, see the REST API specification.

Filtering, sorting, and paginating AppData items

The OpenSocial REST API lets you specify various criteria to apply to the returned collection, such as requesting that the items be sorted in a particular order, or requesting that only a particular set of fields be returned for each AppData item in the collection.
For example, to request that AppData items be ordered by last-updated date, add the orderby parameter to the request URL:

GET http://api.example.org/appdata/userID/appID/selector?orderby=updated

When you send that GET request, the social network returns an HTTP 200 OK status code and a collection of AppData items sorted by date.
For more information about the supported query parameters, see Query parameter reference.

Updating AppData items

To update an existing AppData item, first you retrieve the AppData item you want to update, then you modify it, and then you send an authenticated PUT request, with the updated data in the request body, to the AppData item's URL.
For example, say you've retrieved the following AppData item:

{
  "example.org:34KJDCSKJN2HHF0DW20394" : {"pokes" : 3, "last_poke" : "2008-02-13T18:30:02Z" }
}

Modify it as follows:

{
  "example.org:34KJDCSKJN2HHF0DW20394" : {"pokes" : 4, "last_poke" : "2008-03-13T20:30:02Z" }
}

Then use PUT to send the new AppData item to the AppData item URL. The social network replaces the original AppData item with the newly modified one.
Troubleshooting Tip: Some firewalls block HTTP PUT messages. To get around this, you can include an X-HTTP-Method-Override: PUT header in a POST request.

Deleting AppData items

To delete an AppData item, send an authenticated DELETE request to the AppData item's URL.
Troubleshooting Tip: Some firewalls block HTTP DELETE messages. To get around this, you can include an X-HTTP-Method-Override: DELETE header in a POST request.
Note: To update existing AppData items, see Updating AppData items; don't update by deleting AppData items and then re-adding them.

Appendix: Query parameter reference

The OpenSocial REST API supports the following query parameters:
count
The number of items per page, for a paged collection. A social network may have a default value for this parameter.
fields
A comma-separated list of fields to include in the representation. A social network may have a default value for this parameter; if you want the complete set of fields included, then set fields to @all.
filterBy
The field to apply the filterOp and filterValue parameters to.
filterOp
The operation to use on the filterBy field when filtering. Defaults to contains. Valid values are contains, equals, startsWith, and present.
filterValue
The value to use with filterOp when filtering.
format
The data format to use, such as json (the default) or atom.
indexBy
Indicates that the specified field should be used as an index in the returned JSON mapping.
networkDistance
Indicates that the returned collection should include results for all friends up to this many links away.
sortBy
The field to use in sorting.
sortOrder
The order in which to sort entries: ascending (the default) or descending.
startIndex
The 1-based index of the first result to be retrieved (for paging).
updatedSince
The date to filter by; returns only items with an updated date equal to or more recent than the specified value.
Some social networks may not support all parameters.
For more information about query parameters, see the REST API specification.