OpenSocial Restful Protocol

The RESTful API serves as a common protocol understood by all OpenSocial 0.8-compliant clients and servers.

0. Notation and Conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119]. Domain name examples use [RFC2606].

1. Overview

This API defines a language and platform neutral protocol for clients to interact with OpenSocial container servers outside of gadgets on a web page. As a protocol, it is intended to be reasonably easy to implement in any language and on any platform. It should also be usable across a range of clients, from gadgets operating within a web page to servers communicating to synchronize data about a user.

The protocol operates primarily in terms of resources and operations on them. It is defined on top of the HTTP protocol, and uses the standard HTTP methods (GET, POST, PUT, DELETE, etc.) to retrieve and change server state. 

No single data representation is ideal for every client. This protocol defines representations for each resource in three widely supported formats, JSON [RFC4627], XML, and Atom/AtomPub [RFC4287][RFC5023], using a set of generic mapping rules. The mapping rules allow a server to write to a single interface rather than implementing the protocol three times.

OpenSocial container servers are free to define additional representations but MUST support at least the JSON and Atom formats for all resources and XML for the people calls. XML MAY be supported for the rest of the resources.

The protocol defines Activity, Person, Group, and AppData resources. Most operations consist of retrieving (GET), updating (PUT), creating (POST or PUT), or destroying (DELETE) these resources. It also specifies an optional partial update feature which avoids sending large resources over the wire to update just one field. 

OpenSocial API Background details the underlying concepts used below; this document assumes familiarity with the OpenSocial model.

2. Data Representations

Each resource has three representations, as JSON, XML, and Atom. All data must be representable in each format. The XML and JSON formats have a one to one mapping while the Atom format is defined separately for each type of object and collection. Throughout this document, examples will only be given in JSON and Atom. The XML representation can be mapped directly from the JSON and MUST conform to the XSD in Section 12.

Each resource is represented as a hierarchical tree of elements. Ordering of elements within a parent element may or may not be significant, depending on the context. Mapping consists of converting between the internal hierarchy and the JSON/XML or Atom protocol format.

The set of allowed fields in each type of data is the same as the set documented in Section 11 (field names)

The general rules for mapping between the Atom and JSON formats are as follows. Each data type may add additional aliasing rules.

• The default location for all data in the Atom format is in atom:entry/atom:content/datatype, where datatype is a root node naming the type of data delivered: <person>, <group>, <activity>, or <appdata>.
• The field names are specified at the end of this document in camelCase
  
• Strings are represented as strings in both formats.
• Dates and timestamps are represented as strings containing AtomPub (RFC3339) format date-time elements; see section 3.3 of [RFC4287]. These are also known as "XSD Dates". In cases where only a day-of-the-year is desired, e.g., a birthday, the year SHOULD be specified as 0000.
• Enums are represented as objects with "displayvalue" (localizable, customizable string) and "key" (key) fields.
• Arrays are represented as arrays in the JSON representation and as repeated fields in the XML representation.
• Sub-objects are represented as sub-elements in both formats.
• Fields are placed directly in the root object in the JSON format. In the Atom format, they are by default placed under atom:content/datatype (e.g., atom:content/person for person data). Some fields are 'hoisted' and aliased to standard Atom fields directly underneath atom:entry. There are three standard aliases that apply to all data types:
  • atom:entry/atom:id aliases the "id" field. The JSON format id is the OpenSocial globally unique ID, which consists of the container domain (e.g., example.org) followed by a colon and the container's id for that person. The container specific id can only contain letters (A-Za-z), numbers (0-9), dots (.), hyphens (-) and underscores (_). For example, example.org:78gh37261ddfdf. In the Atom format, it is translated into the required URI data type by prepending "urn:guid:" to the OpenSocial ID string. These rules are intended to make mapping IDs between the RESTful API and the JS API straightforward while preserving global uniqueness.
  • atom:entry/atom:updated aliases the JSON field indicating the most recent update time if available (POSTED_TIME for Activity), or the generation time if no better information is available.
  • atom:entry/atom:published aliases the JSON field indicating creation time (POSTED_TIME for Activity).

Examples of the primary types of data follow. Each example shows both representations, JSON and Atom, with the payload data highlighted for ease of comparison.

2.1 Responses

The structure of the response object returned from a successful request for the JSON or XML formats is as follows. The root element isresponse, which is shown explicitly as the root element in XML format, and is the anonymous root object returned when the format is json (i.e. in JSON, the response returned is the object value of the response node). The response node MUST contain the following child nodes, and MAY contain additional nodes that the Service Provider wishes to add to expose additional data. Note thatstartIndex, itemsPerPage, and totalResults are based on OpenSearch.

• startIndex: the index of the first result returned in this response, relative to the starting index of all results that would be returned if no startIndex had been requested. In general, this will be equal to the value requested by the startIndex, or 0 if no specific startIndex was requested.
• itemsPerPage: the number of results returned per page in this response. In general, this will be equal to the count Query Parameter, but MAY be less if the Service Provider is unwilling to return as many results per page as requested, or if there are less than the requested number of results left to return when starting at the current startIndex. This field MUST be present if and only if a value for count is specified in the request.
• totalResults: the total number of contacts that would be returned if there were no startIndex or count specified. This value tells the Consumer how many total results to expect, regardless of the current pagination being used, but taking into account the current filtering options in the request.
• entry: an array of objects, one for each item matching the request, as defined in Section 7.2 (entry Element). For consistency of parsing, if the request could possibly return multiple items (as is normally the case), this value MUST always be an array of results, even if there happens to be 0 or 1 matching results. If the request is specifically for a single contact (e.g. because the request contains Additional Path Information like /@me/@all/{id} or /@me/@self), then entry MUST be an object containing the single item returned (i.e. "entry": [ { /* first item */ } ] and "entry": { /* only item */ } respectively).

For example:

application/json representation:

{
   "startIndex" : 1
   "itemsPerPage" : 10
   "totalResults" : 100,
   "entry" : [
      {...first item...},
      {...second item...}
      ...
   ]
}

or, for only one item:

xml representation:

<response>
   <startIndex> 1 </startIndex>
   <itemsPerPage> 10 <itemsPerPage>
   <totalResults> 100 <totalResults>
   <entry>...first item...</entry>
   <entry>...second item...</entry> 
      ...
</response>

or, for only one item:

<response>
   <startIndex> 1 </startIndex>
   <itemsPerPage> 10 <itemsPerPage>
   <totalResults> 100 <totalResults>
   <entry>...first item...<entry>
</response>

The atom format uses the JSON to Atom mapping rules described above and has a different base format than the XML: 

application/atom+xml representation:

<feed xmlns="http://www.w3.org/2005/Atom" xmlos:osearch="http://a9.com/-/spec/opensearch/1.1">
  <author><uri>urn:guid:example.org:58UIDCSIOP233FDKK3HD44</uri></author>
  <link rel="next" href="http://api.example.org/..." />
  <osearch:totalResults>100</osearch:totalResults>
  <osearch:startIndex>1</osearch:startIndex>
  <osearch:itemsPerPage>10</osearch:itemsPerPage>
  <entry>...first item...</entry>
  <entry>...second item...</entry>
  ...
</feed>

2.2 Person

A Person contains social network data about a single person. The same record is used for contacts/friends and for profiles.

See Section 11 (field names) for a full list of available fields and their types. See also the general mapping rules in section 2.

A minimal Person example:

application/json representation:

{

  "id" : "example.org:34KJDCSKJN2HHF0DW20394",
  "displayName" : "Janey",
  "name" : {"unstructured" : "Jane Doe"},
  "gender" : "female"
}

application/xml representation:

<person xmlns="http://ns.opensocial.org/2008/opensocial">
  <id></id>
  <displayName></displayName>
  <name>
    <unstructured>Jane Doe</unstructured>
  </name>
  <gender>female</gender>
</person>

application/atom+xml representation:

<entry xmlns="http://www.w3.org/2005/Atom">
  <content type="application/xml">
    <person xmlns="http://ns.opensocial.org/2008/opensocial">
      <name>
        <unstructured>Jane Doe</unstructured>
      </name>
      <gender>female</gender>
    </person>
  </content>
  <title/>
  <updated>2003-12-13T18:30:02Z</updated>
  <author/>
  <id>urn:guid:example.org:34KJDCSKJN2HHF0DW20394</id>
</entry>

Note: The atom:summary element is the appropriate place to put a text or HTML representation of the structured data present in the content element, and the atom:title element is the appropriate place to copy a short descriptive name for the entry, such as name.unstructured. Servers MAY choose to add these or other fields to make their feeds more useful for generic aggregators or tools.

2.3 Group

OpenSocial Groups are owned by people, and are used to tag or categorize people and their relationships. The RESTful API supports querying for the available groups for a given user. The groups are returned as a collection. Each group has a display name, an identifier which is unique within the groups owned by that person, and a URI link.

A Group example:

application/json representation:

{
  "id" : "example.org:34KJDCSKJN2HHF0DW20394/friends",
  "title" : "Peeps",
}

application/xml representation:

<group xmlns="http://ns.opensocial.org/2008/opensocial">
  <id>example.org:34KJDCSKJN2HHF0DW20394/friends</id>
  <title>Peeps</title>
</group>

application/atom+xml representation:

<entry xmlns="http://www.w3.org/2005/Atom">
  <link rel="alternate" href="http://api.example.org/people/example.org:34KJDCSKJN2HHF0DW20394/@friends" />
  <title>Peeps</title>
  <updated>2003-12-13T18:30:02Z</updated>
  <id>urn:guid:example.org:34KJDCSKJN2HHF0DW20394/friends</id>
</entry>

Groups only appear within Group Collections and are used to retrieve a list of available groups for a given person.

2.4 Activity

An OpenSocial Activity represents a short summary or notification of a timestamped event, often with pointers for more information.

See Section 11 (field names) for a full list of available fields and their types. Activities have extensive Atom hoisting rules to ensure maximum compatibility with standard feed processing code:

• atom:entry/atom:title aliases "title"
• atom:entry/atom:summary aliases "body"
• atom:entry/atom:link@rel="self" aliases "url"
• atom:entry/atom:icon aliases "faviconUrl"
• atom:entry/atom:source/atom:title aliases "streamTitle"
• atom:entry/atom:source/atom:link@rel="self" aliases "streamUrl"
• atom:entry/atom:generator/atom:uri aliases "appId"
• atom:entry/atom:author/atom:uri aliases "userId"

A minimal Activity example:

application/json representation:

{
  "id" : "http://example.org/activities/example.org:87ead8dead6beef/self/af3778",
  "title" : "<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"
}

application/xml representation:

<activity xmlns="http://ns.opensocial.org/2008/opensocial">
  <id>http://example.org/activities/example.org:87ead8dead6beef/self/af3778</id>
  <title>&lt;a href=\"foo\"&gt;some activity&lt;/a&gt;</title>
  <updated>2008-02-20T23:35:37.266Z</updated>
  <body>Some details for some activity</body>
  <bodyId>383777272</bodyId>
  <url>http://api.example.org/activity/feeds/.../af3778</url>
  <userId>example.org:34KJDCSKJN2HHF0DW20394</userId>
</activity>

application/atom+xml representation:

<entry xmlns="http://www.w3.org/2005/Atom">
  <category term="status"/>
  <id>http://example.org/activities/example.org:87ead8dead6beef/self/af3778</id>
  <title><a href="foo">some activity</a></title>
  <summary>Some details for some activity</summary>
  <updated>2008-02-20T23:35:37.266Z</updated>
  <link rel="self" type="application/atom+xml" href="http://api.example.org/activity/feeds/.../af3778"/>
  <author><uri>urn:guid:example.org:34KJDCSKJN2HHF0DW20394</uri></author>
  <content>
    <activity xmlns="http://ns.opensocial.org/2008/opensocial">
      <bodyId>383777272</bodyId>
    </activity>
  </content>
</entry>

Note: The title field is a string that may only have the following html tags: <b>, <i>, <a>, <span>. 

The container may ignore this formatting when rendering the activity.

2.5 AppData

AppData stores uninterpreted key/value pairs on behalf of an application. The standard unit of AppData is all of the key/value pairs stored for a given app on behalf of a given user; however, the API supports other types of queries (detailed below). To retrieve a subset of fields, use the fields= selector syntax (detailed below).

An isolated AppData example

The first example is of a collection of key/value pairs for a particular application/user pair:

application/json representation:

{
  "pokes" : 3,
  "last_poke" : "2008-02-13T18:30:02Z"
}

application/xml representation:

<appdata xmlns="http://ns.opensocial.org/2008/opensocial">
  <entry>
    <key>pokes</key>
    <value>3</value>
  </entry>
  <entry>
    <key>last_poke</key>
    <value>2008-02-13T18:30:02Z</value>
  </entry>
</appdata>

application/atom+xml representation:

<entry xmlns="http://www.w3.org/2005/Atom">
  <content type="text/xml">
    <appdata xmlns="http://opensocial.org/2008/opensocial">  
        <pokes>3</pokes>
        <last_poke>2008-02-13T18:30:02Z</last_poke>
      </appdata>
  </content>
  <title/>
  <updated>2003-12-13T18:30:02Z</updated>
  <author><url>urn:guid:example.org:34KJDCSKJN2HHF0DW20394</url></author>
  <id>urn:guid:example.org:34KJDCSKJN2HHF0DW20394</id>
</entry>

An AppData Collection Example

In this example, a client has requested a collection of data that spans multiple users. The result is a collection which, by default, is given a special default JSON representation as a mapping from users to their data. 

application/json representation:

(maps directly to the xml format)

{
  "entry" : {
    "example.org:34KJDCSKJN2HHF0DW20394" : {"pokes" : 3, "last_poke" : "2008-02-13T18:30:02Z" },
    "example.org:58UIDCSIOP233FDKK3HD44" : {"pokes" : 2, "last_poke" : "2007-12-16T18:30:02Z" }
  }
}

application/atom+xml representation:
<feed xmlns="http://www.w3.org/2005/Atom>
  <id>...</id>
  <title>...</title>
  <entry>
    <content type="text/xml">
      <appdata>
        <pokes>3</pokes>
        <last_poke>"2008-02-13T18:30:02Z"</last_poke>
      </appdata>
    </content>
    <title/>
    <updated>2008-02-13T18:30:02Z</updated>
    <author><url>urn:guid:example.org:34KJDCSKJN2HHF0DW20394</url></author>
    <id>urn:guid:example.org:34KJDCSKJN2HHF0DW20394</id>
  </entry>
  <entry>
    <content type="text/xml">
      <appdata>
        <pokes>2</pokes>
        <last_poke>"2007-12-16T18:30:02Z"</last_poke>
      </appdata>
    </content>
    <title/>
    <updated>2007-12-16T18:30:02Z</updated>
    <author><url>uurn:guid:example.org:58UIDCSIOP233FDKK3HD44</url></author>
    <id>urn:guid:example.org:58UIDCSIOP233FDKK3HD44</id>  
  </entry>
</entry>

The data within each field is assumed to be in JSON format and is otherwise uninterpreted.

3. Operations

OpenSocial uses standard HTTP methods: GET to retrieve, PUT to update in place, POST to create new, and DELETE to remove. POST is special; it operates on collections and creates new activities, persons, or app data within those collections, and returns the base URI for the created resource in the Location: header, per AtomPub semantics.

Restricted clients, or clients behind restricted clients, which cannot use PUT or DELETE SHOULD translate PUT and DELETE to POST operations with an additional X-HTTP-Method-Override: header:

    POST /... HTTP/1.1
    ...
    X-HTTP-Method-Override: PUT

Servers SHOULD respond to POST+X-HTTP-Method-Override as if the content of the header were the actual operation sent.

Note: OpenSocial 0.8 does not support cross-domain JSONP (GET with callback), but servers MAY offer this as an extension. It is RECOMMENDED that such servers implement appropriate security and authorization controls.

4. Request Authentication and Authorization Context

Each RESTful operation has a request context that usually includes authentication and authorization information. Typically, the context information includes the requestor id (the user initiating the request) and app ID (the application, or whatever is acting as the user's agent). It may include other container-specific information.

Containers MUST be an OAuth Core 1.0 Service Provider (a web application that allows access via OAuth). Containers MAY also support other ways to establish a request context. Containers MUST also support the Consumer Request OAuth extension, in which the end user has not directly authorized the operation. Applications SHOULD ensure that the users have given prior consent, implicitly or explicitly, to the operation or class of operations. However, containers MAY require an additional prior trust relationship be established by the app in order to allow use of Consumer Request OAuth.

If a Consumer has a user identifier and wishes to indicate that the operation is being done on behalf of that particular user, it SHOULD provide the OAuth extension parameter xoauth_requestor_id with the OAuth signed parameters. Consumers SHOULD only provide this if the user has given prior consent, implicitly or explicitly, to the operation or class of operations, as it indicates that the operation is being done on behalf of the user. Container SPs MUST either honor the parameter or ignore it as if it were not provided.

Thus, a request context usually includes the requesting application (the OAuth Consumer), and may include the requesting user, either implicitly via an oauth_token or explicitly via xoauth_requestor_id. It may also include additional information via extensions or other channels (cookies, URI parameters, client SSL certificates, etc.) A container may also accept requests with no authentication or authorization (authnz) information at all for public data. A container may provide a public version (e.g., of a profile) if no authnz information is provided.

Note that the data provided for a given RESTful URI MAY vary per requestor or app. Thus, the meaning of the resource at a given URI is "the view of the information available to the current requestor/app combination". In the case where no information is available due to lack of authorization, an HTTP 401 Unauthorized response SHOULD be returned to the client. In the case where at least some view of the information is available, it SHOULD be returned using a 200 status, with a standard OAuth WWW-Authenticate: header indicating that additional information may be available when using a different authnz context.

5. Discovery

A container declares what collection and features it supports, and provides templates for discovering them, via a simple discovery document. A client starts the discovery process at the container's identifier URI (e.g., example.org). The full flow is available athttp://xrds-simple.net/core/1.0/; in a nutshell:

1. Client GETs {container-url} with Accept: application/xrds+xml
2. Container responds with either an X-XRDS-Location: header pointing to the discovery document, or the document itself.
3. If the client received an X-XRDS-Location: header, follow it to get the discovery document.

The discovery document is an XML file in the same format used for OpenID and OAuth discovery, defined at http://xrds-simple.net/core/1.0/:

<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>

Each Service advertises a service provided by the container. Each container MUST support the service Types documented below and MAY support others by advertising them in the discovery document. Each service comprises a set of resources defined by the given URI Template (or URI, if there is only a single resource). Clients follow the URIs and instantiate the templates to find and operate on specific resources. (URI Template syntax is documented at http://www.ietf.org/internet-drafts/draft-gregorio-uritemplate-03.txt.)

The set of substitution variables is fixed for each service Type. The core set of service Types and their substitution variables is documented below. Extensions to OpenSocial SHOULD document their substitution variables; note that a reasonable place to put human readable documentation is at the namespace URI.

6. The Core OpenSocial Service Types

This section defines the core types that every OpenSocial container MUST support, their XRDS types, and their semantics. Unless otherwise specified, all HTTP operations are generally allowed for any URI endpoint; a container which wishes to specify the allowed operations SHOULD provide an HTTP Allow: header for each resource listing the allowed operations.

6.1 People

XRDS Type: http://ns.opensocial.org/2008/opensocial/people

• A user-defined local group name to select a group of contacts (a collection)
• @self to select the person record for guid
• @all to select all the universal set of contacts (a collection)
• @friends to select the subset of contacts which are friends (a collection)

People URI examples:
  /people/{guid}/@all                      -- Collection of all people connected to user {guid}
  /people/{guid}/@friends                  -- Collection of all friends of user {guid}; subset of        @all
  /people/{guid}/{groupid}                 -- Collection of all people connected to user {guid} in group {groupid}
  /people/{guid}/@all/{pid}                -- Individual person record for a specific person known to {guid}; shows {guid}'s view of {pid}.
  /people/{guid}/@self                     -- Profile record for user {guid}
  /people/@me/@self                        -- Profile record for requestor
  /people/@supportedFields                 -- Returns all of the fields that the container supports on people objects as an array in json and a repeated list in atom.
  /people/{guid}/@deleted                  -- This is an optional api that will return all of the people connected to the user {guid} that have been deleted. This should usually be combined with a updatedSince param.

Note that a given container may use alternative URI formats; for example,

  /people.cgi?guid={guid}&groupid={groupid}

is a valid URI pattern given the appropriate XRDS discovery document which allows clients to map the parameters to a concrete URI.

Friends may be added by POSTing to the appropriate collection (e.g., /people/{guid}/@friends). Containers MAY require a dual opt-in process before the friend record appears in the collection, and in this case SHOULD return a 202 Accepted response, indicating that the request is 'in flight' and may or may not be ultimately successful.

6.2 Groups

XRDS Type: http://ns.opensocial.org/2008/opensocial/groups

guid : Container-globally-unique user identifier; identifies owner of the people data; can be @me to indicate auth[nz] requestor should be used.

  /groups/{guid}                      -- Collection of groups associated with user {guid}

6.3 Activities

XRDS Type: http://ns.opensocial.org/2008/opensocial/activities

guid : Container-globally-unique user identifier; owner or recipient of the activity data, or @me to indicate the requestor should be used

• A user-defined local group name to select activities from people in the group (a collection)
• @self to select the activities for user guid (a collection)
• @all to select all the universal set of contacts (a collection)
• @friends to select the activities from friends only (a collection)

appId : The app id to select activities for, or @app to indicate the currently requesting application.

Activity URI examples:

/activities/{guid}/@self                -- Collection of activities generated by given user
/activities/{guid}/@self/{appid}        -- Collection of activities generated by an app for a given user
/activities/{guid}/@friends             -- Collection of activities for friends of the given user {guid}
/activities/{guid}/@friends/{appid}     -- Collection of activities generated by an app for friends of the given user {guid}
/activities/{guid}/{groupid}            -- Collection of activities for people in group {groupid} belonging to given user {uid}
/activities/{guid}/{groupid}/{appid}    -- Collection of activities generated by an app for people in group {groupid} belonging to given user {uid}
/activities/{guid}/@self/{appid}/{activityid}   -- Individual activity resource; usually discovered from collection
/activities/@supportedFields            -- Returns all of the fields that the container supports on activity objects as an array in json and a repeated list in atom.

6.4 AppData (http://ns.opensocial.org/2008/opensocial/appdata)

guid : Container-globally-unique user identifier, or @me to indicate the requestor should be used

• A user-defined local group name to select appdata from people in the group (a collection)
• @self to select the appdata for user guid only (a collection)
• @all to select all the universal set of contacts (a collection)
• @friends to select the appdata from friends of guid only (a collection)

appId : The app id to select activities for, or @app to indicate the currently requesting application.

AppData URI examples:

/appdata/{guid}/@self/{appid}                  -- All app data for user {guid}, app {appid}
/appdata/{guid}/@friends/{appid}               -- All app data for friends of user {guid} and app {appid}; read-only (only GET and HEAD supported)
/appdata/{guid}/@self/{appid}?fields=highscore -- Just the highscore field for user {guid}, app {appid}

6.5 Standard Query Parameters

These additional query parameters may be used with any URI above. The parameters startIndex and count are interpreted according to the OpenSearch spec.

count={count}                      -- Requests page size for paged collection. If no parameter is specified the container can choose how many items 
                                      in the collection should be returned. However, the container SHOULD support a large default count value so that 
                                      all items can be returned by default.
filterBy={fieldname}               -- For a collection, return entries filtered by the given field.  
filterOp={operation}               -- The operation to use when filtering a collection, defaults to "contains". Valid values are contains, equals, startsWith, and present.
filterValue={value}                -- The value to use when filtering a collection. For example, filterBy=name&filterOp=startsWith&filterValue=John will 
                                      return all items whose name field starts with John. Johnny and John Doe would both be included.) 
format={format}                    -- Format desired; one of (atom, json, xml); default is json if not provided
fields={-join|,|field}             -- List of fields to include in representation or in the members of a collection. If no fields are provided it is up to 
                                      the container to decide which fields to return. However, the set MUST include the minimum set of fields. 
                                      For people this is id, name, and thumbnailUrl. For activities this is id and title. 
                                      @all is accepted to indicate returning all available fields.   
networkDistance={networkDistance}  -- Modifies group-relative requests (@friends, etc.) to include the transitive closure of all friends up to 
                                      {networkDistance} links away.  May not be honored by the container.
sortBy={fieldname}                 -- For a collection, return entries sorted by the given field.  
sortOrder={order}                  -- Can either be "ascending" or "descending", defaults to ascending. Used to sort objects in a collection.
startIndex={startIndex}            -- Index into a paged collection    
updatedSince={xsdDateTime}         -- When specified the container should only return items whose updated date is equal to or more recent then the specified value.


Note: The container is not required to support all values for filtering, sorting and getting the last set of updated items from a collection. If the 
container does not respect the filer, sort or updatedSince param the response should contain "filtered : false", "sorted : false", or "updatedSince : false".

7. Security Considerations

Containers SHOULD carefully consider security. Containers MUST support OAuth but SHOULD use appropriate policies to determine allowed operations on a per-Consumer and per-user basis. Per the OAuth spec, Containers SHOULD document how a Consumer can direct a user to a Container web page to obtain an oauth_token for future use. Note that this is a vector for phishing if the user is required to enter their credentials.

Containers SHOULD support SSL connections for sensitive data as OAuth on its own does not provide encryption or message body integrity checking. Containers should base their security decisions on the type of client in use; a generally available desktop client, for example, cannot effectively protect a Consumer Secret that is installed with each client. The security of communications with a partner service, on the other hand, is dependent on the effectiveness of that service's security procedures. Containers may wish to rate limit requests from unknown clients, or require registration, in order to mitigate risk.

Containers should scope oauth_tokens as narrowly as possible (e.g., allow reading but not writing if a client only performs reads).

8. Concurrency Control (Optional)

This feature allows a container and client to cooperate in order to prevent multiple containers from overwriting each other's data. It uses the standard HTTP/AtomPub optimistic concurrency mechanism based on ETags (see section 9.5 of [RFC5023] for details; the same mechanism applies regardless of the data format used for the body of the PUT).

8.1 Discovery

Concurrency control is available on a resource-by-resource basis. When an updateable resource supports concurrency control, the container SHOULD supply an ETag encoding the resource's current state when supplying a representation to clients. If a resource does not support optimistic concurrency, it MUST respond to an update request containing an If-Match: header with a 403 Not Implemented error.

A server which chooses not to support optimistic concurrency SHOULD omit ETags on its responses for updateable resources. A client SHOULD assume that optimistic concurrency is not available if no ETag is present.

8.2 Semantics

When a client is given an ETag, it MAY supply that ETag in an If-Match: header on subsequent updates. The semantics are that the client can supply the new representation and the previous ETag; the server inspects the current state of the resource and applies the update if the client supplied ETag matches (meaning no intervening updates have happened), otherwise responds with a 409 Conflict error and the new ETag. Clients may then take appropriate actions to resolve the conflict, or fail the operation, depending on their needs. Clients are also free to use PUT to simply overwrite a resource with a new state at any time, ignoring possible overwriting problems.

If partial updates are supported (see below), a server MUST accept an ETag given for either a base resource or a projection of that resource upon a subsequent PUT for that resource. That is, it is legal to supply an ETag you received when GETting the full representation of a resource even if you are only PUTting back a single field. If you intend to simply overwrite that single field, then you skip sending any ETag.

9. Partial Updates

Partial updates avoid the need to send full representations of data on updates, especially for People and App Data. The primary use case is when a client has retrieved a full representation and subsequently wishes to send a small update to a server. In the most general case, the client may have a series of small updates (e.g., changing tags on a large number of contacts) scattered across many resources. To accomplish these partial updates we will take advantage of the "fields" parameter.

When the "fields" parameter is specified on a url, only those fields will be looked at when updating an object. If a field is in the parameter list but not part of the post, that would be considered a removal of that field. If the field is in the post but not in the parameter list a 400 bad request error will be returned. If a field is in both places then it will be updated normally.

10. Messaging (Optional)

A social network service may optionally expose a mechanism for sending short messages between users. The functionality and policies are parallel to those of the JS API's requestSendMessage.

Discovery

If a container supports messaging, it advertises a "messages" Service in its discovery document:

<Service>
  <Type>http://ns.opensocial.org/2008/opensocial/messages</Type>
  <os:URI-Template>http://api.example.org/messages/{guid}/outbox/{msgid}</os:URI-Template>
</Service>

Semantics

To create a message and place it in a queue, a client PUTs a message to an 'outbox' collection resource discovered from the XRDS document:

PUT /messages/{guid}/outbox/{msgid}

The outbox is owned by the source user. Placing a message in the outbox requests that the message be delivered to one or more recipients. Containers are free to filter or alter the message according to their own policies (such as security or rate limiting policies).

The format of the message is the same as an activity, but with an additional set of recipients (osapi:recipient):

<entry xmlns="http://www.w3.org/2005/Atom"
         xmlns:osapi="http://opensocial.org/2008/opensocialapi">
  <osapi:recipient>example.org:AD38B3886625AAF</osapi:recipient>
  <osapi:recipient>example.org:997638BAA6F25AD</osapi:recipient>
  <title>You have an invitation from Joe</title>
  <id>{msgid}</id>
  <link rel="alternate" href="http://app.example.org/invites/{msgid}"/>
  <content>Click <a href="http://app.example.org/invites/{msgid}">here</a> to review your invitation.</content>
</entry>

The {msgid} is client generated and SHOULD be globally unique. If a client does not care about failure cases, it can alternatively use a standard AtomPub POST to /messages/{source-uid}/outbox and leave generation of the ID to the container. In either case, the response is 201 Created on success.

If not supported, the response code should be 403 Not Implemented.

Typically a container would choose to only allow a PUT to an outbox where the {guid} equals the requestor id, but this is a container security policy decision. Containers may choose to allow messaging only between friends or user other heuristics to prevent spam.

11. Field Names

Each field is defined as either a Singular Field, in which case there can be at most one instance of that field per contact, or as a Plural Field, which case any number of instances of that field may be present per contact.  Unless otherwise specified, all fields are optional and of type xs:string.

11.1 Person

11.1.1 singular person fields

id:

Unique identifier for the Person. Each Person returned MUST include a non-empty id value. This identifier MUST be unique across this user's entire set of people, but MAY not be unique across multiple users' data. It MUST be a stable ID that does not change when the same contact is returned in subsequent requests. For instance, an e-mail address is not a good id, because the same person may use a different e-mail address in the future. Usually, in internal database ID will be the right choice here, e.g. "12345".

displayName:

The name of this Person, suitable for display to end-users. Each Person returned MUST include a non-emptydisplayName value. The name SHOULD be the full name of the Person being described if known (e.g. Cassandra Doll or Mrs. Cassandra Lynn Doll, Esq.), but MAY be a username or handle, if that is all that is available (e.g. doll). The value provided SHOULD be the primary textual label by which this Person is normally displayed by the Service Provider when presenting it to end-users.

name:

The broken-out components and fully formatted version of the person's real name, as described in Section 11.1.3 (name Element).

nickname:

The casual way to address this Person in real life, e.g. "Bob" or "Bobby" instead of "Robert". This field SHOULD NOT be used to represent a user's username (e.g. jsmarr or daveman692); the latter should be represented by the preferredUsername field.

published:

The date this Person was first added to the user's address book or friends list (i.e. the creation date of this entry). The value MUST be a valid xs:dateTime (e.g. 2008-01-23T04:56:22Z).

updated:

The most recent date the details of this Persont were updated (i.e. the modified date of this entry). The value MUST be a valid xd:dateTime (e.g. 2008-01-23T04:56:22Z). If this Person has never been modified since its initial creation, the value MUST be the same as the value of published. Note the updatedSince Query Parameter can be used to select only people whose updated value is equal to or more recent than a given xs:dateTime. This enables Consumers to repeatedly access a user's data and only request newly added or updated contacts since the last access time.

birthday:

The birthday of this person. The value MUST be a valid xs:date (e.g. 1975-02-14. The year value MAY be set to0000 when the age of the Person is private or the year is not available.

anniversary:

The wedding anniversary of this person. The value MUST be a valid xs:date (e.g. 1975-02-14. The year value MAY be set to 0000 when the year is not available.

gender:

The gender of this person. Service Providers SHOULD return one of the following Canonical Values, if appropriate:male, female, or undisclosed, and MAY return a different value if it is not covered by one of these Canonical Values.

note:

Notes about this person, with an unspecified meaning or usage (normally notes by the user about this person). This field MAY contain newlines.

preferredUsername:

The preferred username of this person on sites that ask for a username (e.g. jsmarr or daveman692). This field may be more useful for describing the owner (i.e. the value when /@me/@self is requested) than the user's person, e.g. Consumers MAY wish to use this value to pre-populate a username for this user when signing up for a new service.

utcOffset:

The offset from UTC of this Person's current time zone, as of the time this response was returned. The value MUST conform to the offset portion of xs:dateTime, e.g. -08:00. Note that this value MAY change over time due to daylight saving time, and is thus meant to signify only the current value of the user's timezone offset.

connected:

Boolean value indicating whether the user and this Person have established a bi-directionally asserted connection of some kind on the Service Provider's service. The value MUST be either true or false. The value MUST be true if and only if there is at least one value for the relationship field, described below, and is thus intended as a summary value indicating that some type of bi-directional relationship exists, for Consumers that aren't interested in the specific nature of that relationship. For traditional address books, in which a user stores information about other contacts without their explicit acknowledgment, or for services in which users choose to "follow" other users without requiring mutual consent, this value will always be false.

The following additional Singular Fields are defined, based on their specification in the OpenSocial javascript apis: aboutMe, bodyType,currentLocation, drinker, ethnicity, fashion, happiestWhen, humor, livingArrangement, lookingFor, profileSong,profileVideo, relationshipStatus, religion, romance, scaredOf, sexualOrientation, smoker, and status.

11.1.2 plural person fields

Unless specified otherwise, all Plural Fields have the same three standard sub-fields:

value:

The primary value of this field, e.g. the actual e-mail address, phone number, or URL. When specifying a sortByfield in the Query Parameters for a Plural Field, the default meaning is to sort based on this value sub-field. Each non-empty Plural Field value MUST contain at least the value sub-field, but all other sub-fields are optional.

type:

The type of field for this instance, usually used to label the preferred function of the given contact information. Unless otherwise specified, this string value specifies Canonical Values of work, home, and other. 

primary:

A Boolean value indicating whether this instance of the Plural Field is the primary or preferred value of for this field, e.g. the preferred mailing address or primary e-mail address. Service Providers MUST NOT mark more than one instance of the same Plural Field as primary="true", and MAY choose not to mark any fields as primary, if this information is not available. For efficiency, Service Providers SHOULD NOT mark all non-primary fields with primary="false", but should instead omit this sub-field for all non-primary instances.

When returning Plural Fields, Service Providers SHOULD canonicalize the value returned, if appropriate (e.g. for e-mail addresses and URLs). Providers MAY return the same value more than once with different types (e.g. the same e-mail address may used for work and home), but SHOULD NOT return the same (type, value) combination more than once per Plural Field, as this complicates processing by the Consumer.

emails:

E-mail address for this Person. The value SHOULD be canonicalized by the Service Provider, e.g.joseph@plaxo.com instead of joseph@PLAXO.COM.

urls:

URL of a web page relating to this Person. The value SHOULD be canonicalized by the Service Provider, e.g.http://josephsmarr.com/about/ instead of JOSEPHSMARR.COM/about/. In addition to the standard Canonical Values for type, this field also defines the additional Canonical Values blog and profile.

phoneNumbers:

Phone number for this Person. No canonical value is assumed here. In addition to the standard Canonical Values for type, this field also defines the additional Canonical Values mobile, fax, and pager.

ims:

Instant messaging address for this Person. No official canonicalization rules exist for all instant messaging addresses, but Service Providers SHOULD remove all whitespace and convert the address to lowercase, if this is appropriate for the service this IM address is used for. Instead of the standard Canonical Values for type, this field defines the following Canonical Values to represent currently popular IM services: aim, gtalk, icq, xmpp,msn, skype, qq, and yahoo.

photos:

URL of a photo of this person. The value SHOULD be a canonicalized URL, and MUST point to an actual image file (e.g. a GIF, JPEG, or PNG image file) rather than to a web page containing an image. Service Providers MAY return the same image at different sizes, though it is recognized that no standard for describing images of various sizes currently exists. Note that this field SHOULD NOT be used to send down arbitrary photos taken by this user, but specifically profile photos of the contact suitable for display when describing the contact.

tags:

A user-defined category label for this person, e.g. "favorite" or "web20". These values SHOULD be case-insensitive, and there SHOULD NOT be multiple tags provided for a given person that differ only in case. Note that this field consists only of a string value.

relationships:

A bi-directionally asserted relationship type that was established between the user and this person by the Service Provider. The value SHOULD conform to one of the XFN relationship values (e.g. kin, friend, contact, etc.) if appropriate, but MAY be an alternative value if needed. Note this field is a parallel set of category labels to thetags field, but relationships MUST have been bi-directionally confirmed, whereas tags are asserted by the user without acknowledgment by this Person. Note that this field consists only of a string value.

addresses:

A physical mailing address for this Person, as described in Section 11.1.4 (address Element).

organizations:

A current or past organizational affiliation of this Person, as described in Section 11.1.5 (organization Element).

accounts:

An online account held by this Person, as described in Section 11.1.6 (account Element).

The following additional Plural Fields are defined, based on their specification in OpenSocial: activities, books, cars, children,food, heroes, interests, jobInterests, languages, languagesSpoken, movies, music, pets, politicalViews, quotes, sports,turnOffs, turnOns, and tvShows.

11.1.3 name element

The components of the person's real name. Providers MAY return just the full name as a single string in the formatted sub-field, or they MAY return just the individual component fields using the other sub-fields, or they MAY return both. If both variants are returned, they SHOULD be describing the same name, with the formatted name indicating how the component fields should be combined.

formatted:

The full name, including all middle names, titles, and suffixes as appropriate, formatted for display (e.g. Mr. Joseph Robert Smarr, Esq.). This is the Primary Sub-Field for this field, for the purposes of sorting and filtering.

familyName:

The family name of this Person, or "Last Name" in most Western languages (e.g. Smarr given the full name Mr. Joseph Robert Smarr, Esq.).

givenName:

The given name of this Person, or "First Name" in most Western languages (e.g. Joseph given the full name Mr. Joseph Robert Smarr, Esq.).

middleName:

The middle name(s) of this Person (e.g. Robert given the full name Mr. Joseph Robert Smarr, Esq.).

honorificPrefix:

The honorific prefix(es) of this Person, or "Title" in most Western languages (e.g. Mr. given the full name Mr. Joseph Robert Smarr, Esq.).

honorificSuffix:

The honorifix suffix(es) of this Person, or "Suffix" in most Western languages (e.g. Esq. given the full name Mr. Joseph Robert Smarr, Esq.).

11.1.4 address element

The components of a physical mailing address. Service Providers MAY return just the full address as a single string in the formattedsub-field, or they MAY return just the individual component fields using the other sub-fields, or they MAY return both. If both variants are returned, they SHOULD be describing the same address, with the formatted address indicating how the component fields should be combined.

formatted:

The full mailing address, formatted for display or use with a mailing label. This field MAY contain newlines. This is the Primary Sub-Field for this field, for the purposes of sorting and filtering.

streetAddress:

The full street address component, which may include house number, street name, PO BOX, and multi-line extended street address information. This field MAY contain newlines.

locality:

The city or locality component.

region:

The state or region component.

postalCode:

The zipcode or postal code component.

country:

The country name component.

11.1.5 organization element

Describes a current or past organizational affiliation of this contact. Service Providers that support only a single Company Name and Job Title field should represent them with a single organization element with name and title properties, respectively.

name:

The name of the organization (e.g. company, school, or other organization). This field MUST have a non-empty value for each organization returned. This is the Primary Sub-Field for this field, for the purposes of sorting and filtering.

department:

The department within this organization.

title:

The job title or organizational role within this organization.

type:

The type of organization, with Canonical Values job and school.

startDate:

The date this Person joined this organization. This value SHOULD be a valid xs:date if possible, but MAY be an unformatted string, since it is recognized that this field is often presented as free-text.

endDate:

The date this Person left this organization or the role specified by title within this organization. This value SHOULD be a valid xs:date if possible, but MAY be an unformatted string, since it is recognized that this field is often presented as free-text.

location:

The physical location of this organization. This may be a complete address, or an abbreviated location like "San Francisco".

description:

A textual description of the role this Person played in this organization. This field MAY contain newlines.

11.1.6 account element

Describes an account held by this Person, which MAY be on the Service Provider's service, or MAY be on a different service. Consumers SHOULD NOT assume that this account has been verified by the Service Provider to actually belong to this Person. For each account, the domain is the top-most authoritative domain for this account, e.g. yahoo.com or reader.google.com, and MUST be non-empty. Each account must also contain a non-empty value for either username or userid, and MAY contain both, in which case the two values MUST be for the same account. These accounts can be used to determine if a user on one service is also known to be the same person on a different service, to facilitate connecting to people the user already knows on different services. If Consumers want to turn these accounts into profile URLs, they can use an open-source library like [Social Graph Node Mapper] (Fitzpatrick, B.).

domain:

The top-most authoritative domain for this account, e.g. "twitter.com". This is the Primary Sub-Field for this field, for the purposes of sorting and filtering.

username:

An alphanumeric user name, usually chosen by the user, e.g. "jsmarr".

userid:

A user ID number, usually chosen automatically, and usually numeric but sometimes alphanumeric, e.g. "12345" or "1Z425A".

11.2 Activity

11.2.1 activity fields

11.3 Message

11.3.1 message fields

12. XML format XSD