opensocial-and-gadgets-spec@googlegroups.com

This document describes a method for making social network information and services programatically available on the internet.

Domain name examples use RFC2606.

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. An implementation is not compliant if it fails to satisfy one or more of the MUST or REQUIRED level requirements for the protocols it implements.

The grammatical rules in this document are to be interpreted as described in (Augmented Backus-Naur Form). The following constructs are introduced in this document to augment RFC2234: Elements enclosed in braces (squiggly brackets) are treated as a single, UNORDERED element. Its contents may occur in any order. Hence: {elem foo} bar would match (elem foo bar) and (foo elem bar). NOTE: Specifying alternatives is quite different from specifying set grouping. Alternatives indicate the matching of exactly one (sub-)rule out of the total grouping. The set mechanism indicates the matching of a string which contains all of the elements within the group; however the elements may occur in any order. A construct "#" is defined, similar to "*", for defining lists of elements. The full form is "<n>#<m>element" indicating at least <n> and at most <m> elements, each separated by one or more commas (",") and OPTIONAL linear white space (LWS). This makes the usual form of lists very easy; a rule such as ( *LWS element *( *LWS "," *LWS element )) can be shown as 1#element Wherever this construct is used, null elements are allowed, but do not contribute to the count of elements present. That is, "(element), , (element) " is permitted, but counts as only two elements. Therefore, where at least one element is required, at least one non-null element MUST be present. Default values are 0 and infinity so that "#element" allows any number, including zero; "1#element" requires at least one; and "1#2element" allows one or two. A construct "&" is defined, similar to "#", which uses an ampersand (&) instead of commas, and MUST NOT include linear white space between elements. The grammar described by this specification is word-based. Except where noted otherwise, linear white space (LWS) can be included between any two adjacent words (token or quoted-string), and between adjacent words and separators, without changing the interpretation of a field. At least one delimiter (LWS and/or separators) MUST exist between any two tokens, since they would otherwise be interpreted as a single token.

The following rules are used throughout this specification to describe basic parsing constructs. The US-ASCII coded character set is defined by CHAR = UPALPHA = LOALPHA = ALPHA = UPALPHA / LOALPHA DIGIT = CTL = CR = LF = SP = HT = <"> = CRLF = CR LF LWS = [CRLF] 1*( SP / HT ) TEXT = COMMA = ]]>

OpenSocial defines several services for providing access to a container's data. Individual services are required or optional as indicated in the sections that follow.

Containers MUST support the People Service. Individual operations are required or optional as indicated in the sections that follow. Containers MUST use the following values to define the People Service: XRDS-Type = "http://ns.opensocial.org/2008/opensocial/people" Service-Name = "people"

The Get method supports several different types of queries, from requests for a person or group of people to information about what profile fields are available.

Containers MUST support retrieving information about a person. Requests and responses for retrieving a person use the following values: REST-HTTP-Method = "GET" REST-URI-Fragment = "/people/" User-Id "/@self" REST-Query-Parameters = ENCODE-REST-PARAMETERS(GetPerson-Request-Parameters) REST-Request-Payload = null RPC-Method = "people.get" RPC-Request-Parameters = ENCODE-RPC-PARAMETERS(GetPerson-Request-Parameters) Return-Object = Person If the User-Id is set to -1, the value for the anonymous user MUST be returned. The value for the name and nickname fields can either be blank or set to an appropriate value such as 'Guest', 'Anonymous', etc. The REST protocol also supports queries for a person based on their relationship to a user. In these queries, the URI fragment includes an ID for the initial user, an ID for the group that represents the relationship, and an ID for a user to return: REST-URI-Fragment = "/people/" Initial-User-Id "/" Group-Id "/" Related-User-Id Initial-User-Id = User-Id Related-User-Id = User-Id

A request for a Person object MUST support the Standard-Request-Parameters and the following additional parameters: Name Type Description userId User-Id User ID of person to retrieve. Defaults to "@me", which MUST return the currently logged in user. Note that the userId parameter is not applicable in the REST protocol, as the user is identified in the REST-URI-FRAGMENT. fields Array<String> An array of Person field names. For standard values, see the Person object. escapeType Escape-Type Specifies the type of escaping to use on any AppData values included in the response. Defaults to "htmlEscape". AppData for the person or collection of people returned may be fetched by including "appdata" in the fields parameter. If only a subset of AppData fields are desired, they may be fetched by specifying "appdata.<fieldname>" for each field that needs to be fetched. For example, specifying "appdata.key1,appdata.key2" will return Appdata stored under the keys "key1" and "key2" for the requester.

Here's an example of a REST request to retrieve a person and the associated response. Note that 'format=xml' is used to specify that the response should contain XML. HTTP Request GET /rest/people/34KJDCSKJN2HHF0DW20394/@self?fields=name,gender&format=xml HTTP/1.1 HOST api.example.org Authorization: hh5s93j4hdidpola HTTP Response HTTP/1.1 200 OK Content-Type: text/xml <response xmlns="http://ns.opensocial.org/2008/opensocial"> <person> <id>34KJDCSKJN2HHF0DW20394</id> <name> <unstructured>Jane Doe</unstructured> </name> <gender>female</gender> </person> </response> Here's the same example to retrieve a person and the associated response using the RPC protocol. Note that the URL addressable equivalent is: http://api.example.org/rpc?method=people.get&id=somePerson&userId=34KJDCSKJN2HHF0DW20394&groupId=@self. HTTP Request POST /rpc HTTP/1.1 Host: api.example.org Authorization: hh5s93j4hdidpola Content-Type: application/json { "method" : "people.get", "id" : "somePerson" "params" : { "userId" : "34KJDCSKJN2HHF0DW20394", "fields" : [ "name", "gender" ] } } HTTP Response HTTP/1.x 207 Multi-Status Content-Type: application/json { "id" : "somePerson" "result" : { "id" : "34KJDCSKJN2HHF0DW20394", "name" : { "unstructured" : "Jane Doe"}, "gender" : "female" } }

Containers MUST support retrieving information about multiple people in a single request. Requests and responses for retrieving a list of people use the following values: REST-HTTP-Method = "GET" REST-URI-Fragment = "/people/" User-Id "/" Group-Id REST-Query-Parameters = ENCODE-REST-PARAMETERS(GetPeople-Request-Parameters) REST-Request-Payload = null RPC-Method = "people.get" RPC-Request-Parameters = ENCODE-RPC-PARAMETERS(GetPeople-Request-Parameters) Return-Object = Collection<Person> Note that the Group-Id can't be '@self' in these requests or only a single Person will be returned.

A request for a Collection of Person objects MUST support the Standard-Request-Parameters, the Collection-Request-Parameters, and the following additional parameters: Name Type Description userId User-Id or Array<User-Id> User ID of person or people to retrieve. Defaults to "@me", which MUST return the currently logged in user. groupId Group-Id The Group ID of the group of users related to User ID. Defaults to "@self", which MUST return only the Person object(s) specified by the userId parameter. fields Array<String> An array of Person field names. For standard values, see the Person object. networkDistance number Containers MAY support the network distance parameter, which modifies group-relative requests (@friends, etc.) to include the transitive closure of all friends up to the specified distance away.

Here's an example of a REST request to retrieve the list of a user's friends, and the associated response. Note that 'format=xml' is used to specify that the response should contain XML. HTTP Request GET /rest/people/92WEGDFEWSS2GS0DW274EQ/@friends?fields=name,gender&format=xml HTTP/1.1 HOST api.example.org Authorization: hh5s93j4hdidpola HTTP Response HTTP/1.1 200 OK Content-Type: text/xml <response xmlns="http://ns.opensocial.org/2008/opensocial"> <startIndex> 1 </startIndex> <itemsPerPage> 2 </itemsPerPage> <totalResults> 100 </totalResults> <entry> <person> <id>34KJDCSKJN2HHF0DW20394</id> <name> <unstructured>Jane Doe</unstructured> </name> <gender>female</gender> </person> </entry> <entry> <person> <id>VMK92BFH3DNWRYX39673DF</id> <name> <unstructured>John Smith</unstructured> </name> <gender>male</gender> </person> </entry> </response> Here's an example of a RPC request to retrieve the list of a user's friends, and the associated response. HTTP Request POST /rpc HTTP/1.1 Host: api.example.org Authorization: hh5s93j4hdidpola Content-Type: application/json { "method" : "people.get", "id" : "someFriends" "params" : { "userId" : "92WEGDFEWSS2GS0DW274EQ", "groupId" : "@friends", "fields" : "name, gender" } } HTTP Response HTTP/1.x 207 Multi-Status Content-Type: application/json { "id" : "someFriends" "result" : { "startIndex" : 1 "itemsPerPage" : 2 "totalResults" : 100 "entry" : [ { "id" : "34KJDCSKJN2HHF0DW20394", "name" : { "unstructured" : "Jane Doe"}, "gender" : "female" }, { "id" : "VMK92BFH3DNWRYX39673DF", "name" : { "unstructured" : "John Smith"}, "gender" : "female" } ] } }

Containers MAY support REST requests for supported person fields. Requests and responses for retrieving supported person fields use the following values: REST-HTTP-Method = "GET" REST-URI-Fragment = "/people/@supportedFields" REST-Query-Parameters = null REST-Request-Payload = null Return-Object = Array<String>

Containers MAY support REST requests for a list of people who are no longer friends with a given user. This request SHOULD be combined with a updatedSince param. Requests and responses for retrieving deleted friends use the following values: REST-HTTP-Method = "GET" REST-URI-Fragment = "/people/" User-Id "/@deleted" REST-Query-Parameters = ENCODE-REST-PARAMETERS(GetPeople-Request-Parameters) REST-Request-Payload = null Return-Object = Collection<Person>

Containers MAY support request to create a new relationships between users. This is a generalization of many use cases including invitation, and contact creation. 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. Requests and responses for creating a relationship use the following values: REST-HTTP-Method = "POST" REST-URI-Fragment = "/people/" User-Id "/" Group-Id REST-Query-Parameters = null REST-Request-Payload = Person RPC-Method = "people.create" RPC-Request-Parameters = ENCODE-RPC-PARAMETERS(CreateRelationship-Request-Parameters) Return-Object = null

A request to create a relationship MUST support the Standard-Request-Parameters and the following additional parameters: Name Type Description userId User-Id User ID of the person initiating the relationship request. Defaults to "@me", which MUST return the currently logged in user. groupId Group-Id The Group ID specifying the type of relationship. Defaults to "@friends". person Person The target of the relationship.

Here is an example of a request to create a friend relationship using the REST protocol. In this example, the target user (specified in the post body) needs to accept the invitation before being added to the collection, as indicated by the 202 Accepted response. HTTP Request POST /rest/people/@self/@friends HTTP/1.1 HOST api.example.org Authorization: hh5s93j4hdidpola Content Type: application/xml <entry xmlns="http://ns.opensocial.org/2008/opensocial"> <id>example.org:34KJDCSKJN2HHF0DW20394</id> </entry> HTTP Response HTTP/1.1 202 Accepted Here is an example of a request to create a friend relationship using the RPC protocol: POST /rpc HTTP/1.1 Host: api.example.org Authorization: <auth token> Content-Type: application/json { "method" : "people.create", "id" : "createFriend" "params: { "userId" : "@me", "groupId" : "@friends", "person" : { "id" : "example.org:FF256337" } } } If successful, the associated response contains no data: HTTP/1.x 207 Multi-Status Content-Type: application/json { "id" : "createFriend", "result" : {} } The URL-addressable equivalent of this RPC request is: http://api.example.org/rpc?method=people.create&id=createFriend&userId=@me&groupId=@friends&person.id=example.org:FF256337

Containers MAY support updating the properties of a Person object. If the request is successful, the container MUST return the updated Person object. Requests and responses for updating the fields of a Person use the following values: REST-HTTP-Method = "POST" REST-URI-Fragment = "/people/" User-Id "/" Group-Id REST-Query-Parameters = null REST-Request-Payload = Person RPC-Method = "people.update" RPC-Request-Parameters = ENCODE-RPC-PARAMETERS(UpdatePerson-Request-Parameters) Return-Object = Person

A request to update a person MUST support the Standard-Request-Parameters and the following additional parameters: Name Type Description userId User-Id User ID of the person initiating the update request. Defaults to "@me", which MUST return the currently logged in user. groupId Group-Id The Group ID specifying the type of relationship. Defaults to "@self". person Person A Person object containing the updated fields.

Containers MAY support requests to remove a Person. The default value for User-Id is "@me". Requests and responses to remove a Person use the following values: REST-HTTP-Method = "DELETE" REST-URI-Fragment = "/people/" User-Id "/@self" REST-Query-Parameters = null REST-Request-Payload = null RPC-Method = "people.delete" RPC-Request-Parameters = "{" <"> "userId" <"> ":" <"> User-Id <"> "}" Return-Object = null

Containers MAY support the Groups Service. Individual operations are required or optional as indicated in the sections that follow. Containers that do support groups MUST use the following values to define the Groups Service: XRDS-Type = "http://ns.opensocial.org/2008/opensocial/groups" Service-Name = "groups"

Containers MUST support retrieving information about one or multiple groups in a single request. Requests and responses for retrieving groups use the following values: REST-HTTP-Method = "GET" REST-URI-Fragment = "/groups/" User-Id [ "/" Group-Id ] REST-Query-Parameters = ENCODE-REST-PARAMETERS(GetGroups-Request-Parameters) REST-Request-Payload = null RPC-Method = "groups.get" RPC-Request-Parameters = ENCODE-RPC-PARAMETERS(GetGroups-Request-Parameters) Return-Object = Group / Collection<Group>

A request to create a group MUST support the Standard-Request-Parameters and the following additional parameters: Name Type Description userId User-Id User ID of the person initiating the group request. Defaults to "@me", which MUST return the currently logged in user. groupId Group-Id Optional. Group Id of the single group to be returned by the request.

Containers MAY support the creation of groups. Requests and responses for creating a group use the following values: REST-HTTP-Method = "POST" REST-URI-Fragment = "/groups/" User-Id REST-Query-Parameters = null REST-Request-Payload = Group RPC-Method = "groups.create" RPC-Request-Parameters = ENCODE-RPC-PARAMETERS(CreateGroup-Request-Parameters) Return-Object = Group

A request to create a group MUST support the Standard-Request-Parameters and the following additional parameters: Name Type Description userId User-Id User ID of the person initiating the group creation request. Defaults to "@me", which MUST return the currently logged in user. group Group Group object specifying group to be created. The Group "id" parameter should not be included in the request and MAY be ignored by the container

The update operation will update a group. Containers MAY support this request. REST-HTTP-Method = "PUT" REST-URI-Fragment = "/groups/" User-Id "/" Group-Id REST-Query-Parameters = null REST-Request-Payload = Group RPC-Method = "groups.update" RPC-Request-Parameters = ENCODE-RPC-PARAMETERS(UpdateGroup-Request-Parameters) Return-Object = Group

A request to update a group MUST support the Standard-Request-Parameters and the following additional parameters: Name Type Description userId User-Id User ID of the person initiating the update request. Defaults to "@me", which MUST return the currently logged in user. group Group A Group object containing the updated fields.

Containers MAY support requests to remove a Group. Requests and responses to remove a Group use the following values: REST-HTTP-Method = "DELETE" REST-URI-Fragment = "/groups/" User-Id "/" Group-Id REST-Query-Parameters = null REST-Request-Payload = null RPC-Method = "groups.delete" RPC-Request-Parameters = "{" <"> "groupId" <"> ":" <"> Group-Id <"> "}" Return-Object = null

A request to create a group MUST support the Standard-Request-Parameters and the following additional parameters: Name Type Description userId User-Id User ID of the person initiating the group deletion request. Defaults to "@me", which MUST return the currently logged in user. groupId Group-Id Group ID specifying group to be deleted.

Containers MUST support the Activities Service. Individual operations are required or optional as indicated in the sections that follow. Containers MUST use the following values to define the Activities Service: XRDS-Type = "http://ns.opensocial.org/2008/opensocial/activities" Service-Name = "activities"

The Get method supports multiple queries, including requests for activities and requests for information about what profile fields are available.

Containers MUST support request for Activities. Requests and responses for retrieving activites use the following values: REST-HTTP-Method = "GET" REST-URI-Fragment = "/activities/" User-Id "/" Group-Id [ "/" App-Id [ "/" (Activity-Id / Array<Activity-Id>) ] ] REST-Query-Parameters = ENCODE-REST-PARAMETERS(GetActivities-Request-Parameters) REST-Request-Payload = null RPC-Method = "activities.get" RPC-Request-Parameters = ENCODE-RPC-PARAMETERS(GetActivities-Request-Parameters) Return-Object = Activity Activity-Id = Object-Id

A request for a Collection of Activity objects MUST support the Standard-Request-Parameters, the Collection-Request-Parameters, and the following additional parameters: Name Type Description userId User-Id or Array<User-Id> User ID(s) of the person whose activities are to be returned. Defaults to "@me", indicating the currently authenticated user. In the REST protocol, userId is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. groupId Group-Id The group ID of the group of users whose activities are to be returned. Defaults to "@self", which MUST return only the Activity objects specified by the userId parameter. In the REST protocol, the groupId is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. appId Object-Id Optional. Specifies that the response should only contain activities generated by the given appId. If not included, the container MUST return activities created by the currently authenticated app. In the REST protocol, the appId is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. activityIds Array<Object-Id> Optional. Specifies a list of individual activities to include in the response. In the REST protocol, the activityIds are specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters.

Containers MAY support REST requests for supported Activity fields. Requests and responses for retrieving supported Activity fields use the following values: REST-HTTP-Method = "GET" REST-URI-Fragment = "/activites/@supportedFields" REST-Query-Parameters = null REST-Request-Payload = null Return-Object = Array<String>

Containers MUST support creating an Activity object associated with the currently authenticated app. If successful, the container MUST return the ID of the newly-created Activity. For details on uploading content associated with an activity, see the Content Upload section of . Requests and responses to create an activity use the following values: REST-HTTP-Method = "POST" REST-URI-Fragment = "/activities/" User-Id "/@self" REST-Query-Parameters = null REST-Request-Payload = Activity RPC-Method = "activities.create" RPC-Request-Parameters = ENCODE-RPC-PARAMETERS(CreateActivities-Request-Parameters) Return-Object = Activity-Id Activity-Id = Object-Id

A request to create an Activity MUST support the Standard-Request-Parameters, and the following additional parameters: Name Type Description userId User-Id User ID of the person to associate the activity with. Defaults to "@me", indicating the currently authenticated user. In the REST protocol, userId is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. activity Activity The activity to associate with the given user.

Containers MAY support updating an Activity object associated with the currently authenticated app. For details on uploading content associated with an activity, see the Content Upload section of . Requests and responses to update an activity use the following values: REST-HTTP-Method = "PUT" REST-URI-Fragment = "/activities/" User-Id "/@self" REST-Query-Parameters = null REST-Request-Payload = Activity RPC-Method = "activities.update" RPC-Request-Parameters = ENCODE-RPC-PARAMETERS(UpdateActivities-Request-Parameters) Return-Object = Activity

A request to update an Activity MUST support the Standard-Request-Parameters, and the following additional parameters: Name Type Description userId User-Id User ID(s) of the person the activity is associated with. Defaults to "@me", indicating the currently authenticated user. activity Activity The activity to update. Only the 'id' field of the activity is required.

Containers MAY support deleting an Activity object associated with the currently authenticated app. Requests and responses to update an activity use the following values: REST-HTTP-Method = "DELETE" REST-URI-Fragment = "/activities/" User-Id "/@self" REST-Query-Parameters = null REST-Request-Payload = Activity RPC-Method = "activities.delete" RPC-Request-Parameters = ENCODE-RPC-PARAMETERS(DeleteActivities-Request-Parameters) Return-Object = null

A request to delete an Activity MUST support the Standard-Request-Parameters, and the following additional parameters: Name Type Description userId User-Id User ID(s) of the person the activity is associated with. Defaults to "@me", indicating the currently authenticated user. activity Activity The activity to delete. Only the 'id' field of the activity is required.

Containers MAY support the AppData Service. If the service is supported, individual operations are required or optional as indicated in the sections that follow. The AppData Service provides a data store that applications can use to read and write user-specific data. This data store can be read by anyone who can see the gadget, but only the currently authenticated user's data is writable. Containers MAY implement quotas or rate limits to preserve their disk space. Containers SHOULD provide at least 10KB of space per user per application for storage. Containers MUST use the following values to define the AppData Service: XRDS-Type = "http://ns.opensocial.org/2008/opensocial/appdata" Service-Name = "appdata"

The AppData Service MUST support requests to retrieve AppData. Since AppData is often created based on user inputs, containers MUST perform automatic HTML escaping of all AppData when returning it to the client. However, developers MUST have the option of turning off this escaping via the escapeType parameter. Requests and responses to retrieve AppData use the following values: REST-HTTP-Method = "GET" REST-URI-Fragment = "/appdata/" User-Id "/" Group-Id [ "/" App-Id ] REST-Query-Parameters = ENCODE-REST-PARAMETERS(GetAppData-Request-Parameters) REST-Request-Payload = null RPC-Method = "appdata.get" RPC-Request-Parameters = ENCODE-RPC-PARAMETERS(GetAppData-Request-Parameters) Return-Object = AppData

A request to retrieve AppData MUST support the Standard-Request-Parameters, the Collection-Request-Parameters, and the following additional parameters: Name Type Description userId User-Id or Array<User-Id> User ID(s) of the person whose AppData is to be returned. Defaults to "@me", indicating the currently authenticated user. In the REST protocol, userId is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. groupId Group-Id The group ID of the group of users whose AppData is to be returned. Defaults to "@self", which MUST return only the AppData objects specified by the userId parameter. In the REST protocol, the groupId is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. appId Object-Id Optional. Specifies that the response should only contain AppData generated by the given appId. If not included, the container MUST return AppData created by the currently authenticated app. In the REST protocol, the appId is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. fields Array<Object-Id> A list of AppData keys specifying the fields to retrieve. escapeType Escape-Type Specifies the type of escaping to use on AppData values. Defaults to "htmlEscape".

AppData is created using the update method.

The AppData Service MUST support requests to update AppData for the currently authenticated user. The AppData Service MUST not support request to uppdate AppData for arbitrary users. If an update request is received for an unknown AppData key, the container MUST create an AppData entry for that key. Requests and responses to update AppData use the following values: REST-HTTP-Method = "PUT" REST-URI-Fragment = "/appdata/" User-Id "/@self" [ "/" App-Id ] REST-Query-Parameters = null REST-Request-Payload = AppData RPC-Method = "appdata.update" RPC-Request-Parameters = ENCODE-RPC-PARAMETERS(UpdateAppData-Request-Parameters) Return-Object = null

A request to update AppData MUST support the Standard-Request-Parameters, and the following additional parameters: Name Type Description userId User-Id User ID of the person to associate the AppData with. Defaults to "@me", indicating the currently authenticated user. In the REST protocol, userId is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. appId Object-Id Optional. Specifies that the response should only contain AppData generated by the given appId. If not included, the container MUST return AppData created by the currently authenticated app. data AppData The AppData to create or update.

Here's an example of updating AppData for a user using the RPC protocol: HTTP Request POST /rpc HTTP/1.1 Host: api.example.org Authorization: <auth token> Content-Type: application/json { "method" : "appdata.update", "id" : "setMyData" "params: { "appId" : "app12345", "data" : { "pokes" : 3, "lastPoke" : "2008-02-13T18:30:02Z" } } } HTTP Response HTTP/1.x 207 Multi-Status Content-Type: application/json { "result" : {} } The URL-addressable equivalent is: http://api.example.org/rpc?method=appdata.update&id=setMyData&appId=app12345&data.pokes=3&data.lastPoke=2008-02-13T18:30:02Z.

The AppData Service MUST support requests to remove AppData for the currently authenticated user. The AppData Service MUST not support request to remove AppData for arbitrary users. If the request is successful, the container MUST return the AppData that was removed. Requests and responses to delete AppData use the following values: REST-HTTP-Method = "DELETE" REST-URI-Fragment = "/appdata/" User-Id "/@self" [ "/" App-Id ] REST-Query-Parameters = null REST-Request-Payload = null RPC-Method = "appdata.delete" RPC-Request-Parameters = ENCODE-RPC-PARAMETERS(DeleteAppData-Request-Parameters) Return-Object = AppData

A request to delete AppData MUST support the Standard-Request-Parameters, and the following additional parameters: Name Type Description userId User-Id User ID of the person the AppData belongs to. Defaults to "@me", indicating the currently authenticated user. In the REST protocol, userId is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. appId Object-Id Optional. Specifies that the response should only contain AppData generated by the given appId. If not included, the container MUST return AppData created by the currently authenticated app. keys Array<Object-Id> The keys of the AppData to delete.

Containers MAY support the Albums Service. If the service is supported, individual operations are required or optional as indicated in the sections that follow. Containers MUST use the following values to define the Albums Service: XRDS-Type = "http://ns.opensocial.org/2008/opensocial/albums" Service-Name = "albums"

The Albums Service MUST support requests to retrieve Albums. Requests and responses to retrieve Albums use the following values: REST-HTTP-Method = "GET" REST-URI-Fragment = "/albums/" User-Id "/" Group-Id [ "/" (Album-Id / Array<Album-Id>) ] REST-Query-Parameters = ENCODE-REST-PARAMETERS(GetAlbums-Request-Parameters) REST-Request-Payload = null RPC-Method = "albums.get" RPC-Request-Parameters = ENCODE-RPC-PARAMETERS(GetAlbums-Request-Parameters) Return-Object = Album / Collection<Album> Album-Id = Object-Id

A request to retrieve Albums MUST support the Standard-Request-Parameters, the Collection-Request-Parameters, and the following additional parameters: Name Type Description userId User-Id or Array<User-Id> User ID(s) of the person whose Albums are to be returned. Defaults to "@me", indicating the currently authenticated user. In the REST protocol, userId is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. groupId Group-Id The group ID of the group of users whose Albums are to be returned. Defaults to "@self", which MUST return only the Albums specified by the userId parameter. In the REST protocol, the groupId is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. appId Object-Id Optional. Specifies that the response should only contain Albums generated by the given appId. If not included, the container MUST return Albums created by the currently authenticated app. In the REST protocol, the appId is not used, indicating the container MUST return Albums created by the currently authenticated app. id Array<Object-Id> A list of Album IDs specifying the Albums to retrieve.

The Albums Service MAY support requests to create an Album for the currently authenticated user and app. If successful, the container MUST return the ID of the newly-created Album. Requests and responses to create Albums use the following values: REST-HTTP-Method = "POST" REST-URI-Fragment = "/albums/" User-Id "/@self" REST-Query-Parameters = null REST-Request-Payload = Album RPC-Method = "albums.create" RPC-Request-Parameters = ENCODE-RPC-PARAMETERS(CreateAlbum-Request-Parameters) Return-Object = Album-Id Album-Id = Object-Id

A request to create an Album MUST support the Standard-Request-Parameters, and the following additional parameters: Name Type Description userId User-Id User ID of the person to associate the Album with. Defaults to "@me", indicating the currently authenticated user. In the REST protocol, userId is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. data Album The Album to associate with the given user. In the REST protocol, the Album is included in the REST-Request-Payload, rather than in the REST-Query-Parameters.

The Albums Service MAY support requests to update an Album owned by the currently authenticated user and app. Requests and responses to update Albums use the following values: REST-HTTP-Method = "PUT" REST-URI-Fragment = "/albums/" User-Id "/@self/" Album-Id REST-Query-Parameters = null REST-Request-Payload = Album RPC-Method = "albums.update" RPC-Request-Parameters = ENCODE-RPC-PARAMETERS(UpdateAlbum-Request-Parameters) Return-Object = null Album-Id = Object-Id

A request to update an Album MUST support the Standard-Request-Parameters, and the following additional parameters: Name Type Description userId User-Id User ID of the person the Album is associated with. Defaults to "@me", indicating the currently authenticated user. In the REST protocol, userId is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. data Album The Album to update. In the REST protocol, the Album is included in the REST-Request-Payload, rather than in the REST-Query-Parameters.

The Albums Service MAY support requests to delete an Album owned by the currently authenticated user and app. Requests and responses to delete Albums use the following values: REST-HTTP-Method = "DELETE" REST-URI-Fragment = "/albums" User-Id "/@self/" Album-Id REST-Query-Parameters = null REST-Request-Payload = null RPC-Method = "albums.delete" RPC-Request-Parameters = ENCODE-RPC-PARAMETERS(DeleteAlbum-Request-Parameters) Return-Object = null Album-Id = Object-Id

A request to delete an Album MUST support the Standard-Request-Parameters, and the following additional parameters: Name Type Description userId User-Id User ID of the person the Album is associated with. Defaults to "@me", indicating the currently authenticated user. In the REST protocol, userId is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. id Object-Id The ID of the Album to delete. In the REST protocol, the Album ID is included in the REST-URI-Fragment, rather than in the REST-Query-Parameters.

Containers MAY support the MediaItems Service. If the service is supported, individual operations are required or optional as indicated in the sections that follow. Containers MUST use the following values to define the MediaItems Service: XRDS-Type = "http://ns.opensocial.org/2008/opensocial/mediaItems" Service-Name = "mediaItems"

The MediaItems Service MUST support requests to retrieve MediaItems. Requests and responses to retrieve MediaItems use the following values: REST-HTTP-Method = "GET" REST-URI-Fragment = "/mediaItems/" User-Id "/" Group-Id [ "/" Album-Id [ "/" MediaItem-Id ] ] REST-Query-Parameters = ENCODE-REST-PARAMETERS(GetMediaItems-Request-Parameters) REST-Request-Payload = null RPC-Method = "mediaItems.get" RPC-Request-Parameters = ENCODE-RPC-PARAMETERS(GetMediaItems-Request-Parameters) Return-Object = MediaItem / Collection<MediaItem> Album-Id = Object-Id MediaItem-Id = Object-Id

A request to retrieve MediaItems MUST support the Standard-Request-Parameters, the Collection-Request-Parameters, and the following additional parameters: Name Type Description userId User-Id or Array<User-Id> User ID(s) of the person whose MediaItems are to be returned. Defaults to "@me", indicating the currently authenticated user. In the REST protocol, userId is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. groupId Group-Id The group ID of the group of users whose MediaItems are to be returned. Defaults to "@self", which MUST return only the MediaItems specified by the userId parameter. In the REST protocol, the groupId is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. albumId Object-Id The ID of the album whose MediaItems are to be returned. If no albumId is provided, then the container SHOULD return media items from all albums. In the REST protocol, the albumId is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. appId App-Id Optional. Specifies that the response should only contain MediaItems generated by the given appId. If not included, the container MUST return MediaItems created by the currently authenticated app. In the REST protocol, the appId is not used, indicating the container MUST return MediaItems created by the currently authenticated app. id Array<Object-Id> A list of MediaItem IDs specifying the MediaItems to retrieve.

The MediaItems Service MAY support requests to create a MediaItem for the currently authenticated user and app. If successful, the container MUST return the ID of the newly-created MediaItem. Requests and responses to create a MediaItem use the following values: REST-HTTP-Method = "POST" REST-URI-Fragment = "/mediaItem/" User-Id "/@self/" Album-Id REST-Query-Parameters = null REST-Request-Payload = MediaItem RPC-Method = "mediaItem.create" RPC-Request-Parameters = ENCODE-RPC-PARAMETERS(CreateMediaItem-Request-Parameters) Return-Object = MediaItem-Id Album-Id = Object-Id MediaItem-Id = Object-Id

A request to create an MediaItem MUST support the Standard-Request-Parameters, and the following additional parameters: Name Type Description userId User-Id User ID of the person to associate the MediaItem with. Defaults to "@me", indicating the currently authenticated user. In the REST protocol, userId is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. data MediaItem The MediaItem to associate with the given user. In the REST protocol, the MediaItem is included in the REST-Request-Payload, rather than in the REST-Query-Parameters.

The MediaItems Service MAY support requests to update an MediaItem owned by the currently authenticated user and app. Requests and responses to update a MediaItem use the following values: REST-HTTP-Method = "PUT" REST-URI-Fragment = "/mediaItems/" User-Id "/@self/" Album-Id "/" MediaItem-Id REST-Query-Parameters = null REST-Request-Payload = MediaItem RPC-Method = "mediaItems.update" RPC-Request-Parameters = ENCODE-RPC-PARAMETERS(UpdateMediaItem-Request-Parameters) Return-Object = null Album-Id = Object-Id MediaItem-Id = Object-Id

A request to update an MediaItem MUST support the Standard-Request-Parameters, and the following additional parameters: Name Type Description userId User-Id User ID of the person the MediaItem is associated with. Defaults to "@me", indicating the currently authenticated user. In the REST protocol, userId is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. data MediaItem The MediaItem to update. In the REST protocol, the MediaItem is included in the REST-Request-Payload, rather than in the REST-Query-Parameters.

The MediaItems Service MAY support requests to delete an MediaItem owned by the currently authenticated user and app. Requests and responses to delete a MediaItem use the following values: REST-HTTP-Method = "DELETE" REST-URI-Fragment = "/mediaItems/" User-Id "/@self/" Album-Id "/" MediaItem-Id REST-Query-Parameters = null REST-Request-Payload = null RPC-Method = "mediaItems.delete" RPC-Request-Parameters = ENCODE-RPC-PARAMETERS(DeleteMediaItem-Request-Parameters) Return-Object = null Album-Id = Object-Id MediaItem-Id = Object-Id

A request to delete an MediaItem MUST support the Standard-Request-Parameters, and the following additional parameters: Name Type Description userId User-Id User ID of the person the MediaItem is associated with. Defaults to "@me", indicating the currently authenticated user. In the REST protocol, userId is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. id Object-Id The ID of the MediaItem to delete. In the REST protocol, the MediaItem ID is included in the REST-URI-Fragment, rather than in the REST-Query-Parameters.

Containers MAY support the Messages Service. Containers MAY choose to allow messaging only between friends or use other heuristics to prevent spam. If the service is supported, individual operations are required or optional as indicated in the sections that follow. Containers MUST use the following values to define the Messages Service: XRDS-Type = "http://ns.opensocial.org/2008/opensocial/messages" Service-Name = "messages"

The Messages Service MAY support requests to retrieve Messages. If a Message-Collection-Id is not provided, the response will contain a Collection of available Message-Collection-Ids for the given user. If a Message-Id is not provided, the response will contain a Collection of all messages in the specified message collection. Requests and responses to retrieve Messages use the following values: REST-HTTP-Method = "GET" REST-URI-Fragment = "/messages/" User-Id [ "/" Message-Collection-Id [ "/" Message-Id ] ] REST-Query-Parameters = ENCODE-REST-PARAMETERS(GetMessages-Request-Parameters) REST-Request-Payload = null RPC-Method = "messages.get" RPC-Request-Parameters = ENCODE-RPC-PARAMETERS(GetMessages-Request-Parameters) Return-Object = Collection<Message-Collection-Id> / Message / Collection<Message> Message-Id = Object-Id

A request to retrieve Messages MUST support the Standard-Request-Parameters, the Collection-Request-Parameters, and the following additional parameters: Name Type Description userId User-Id or Array<User-Id> User ID(s) of the person whose Messages are to be returned. Defaults to "@me", indicating the currently authenticated user. In the REST protocol, userId is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. messageCollectionId Message-Collection-Id The ID of the message collection whose Messages are to be returned. If the messageCollectionId is not provided, the response will contain a Collection of available message collection IDs. In the REST protocol, the messageCollectionId is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. messageId Object-Id The ID of the Message to be returned. If no messageId is provided, then the container SHOULD all messages in the given message collection. In the REST protocol, the messageId is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. appId Object-Id Optional. Specifies that the response should only contain Messages generated by the given appId. If not included, the container MUST return Messages created by the currently authenticated app. In the REST protocol, the appId is not used, indicating the container MUST return Messages created by the currently authenticated app.

The Messages Service MUST support requests to send a Message for the currently authenticated user and app. Placing a message in the outbox requests that the message be delivered to one or more recipients as specified in the message. Containers are free to filter or alter the message according to their own policies (such as security or rate limiting policies). If successful, the container MUST return the ID of the newly-created Message. Requests and responses to create a Messages use the following values: REST-HTTP-Method = "POST" REST-URI-Fragment = "/messages/" User-Id "/@self/@outbox" REST-Query-Parameters = null REST-Request-Payload = Message RPC-Method = "messages.send" RPC-Request-Parameters = ENCODE-RPC-PARAMETERS(SendMessage-Request-Parameters) Return-Object = Message-Id Message-Id = Object-Id

A request to send a message MUST support the Standard-Request-Parameters, and the following additional parameters: Name Type Description userId User-Id User ID of the person sending the Message. Defaults to "@me", indicating the currently authenticated user. In the REST protocol, userId is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. message Message The Message to send. In the REST protocol, the Message is included in the REST-Request-Payload, rather than in the REST-Query-Parameters.

The Messages Service MAY support requests to create a message collection for the currently authenticated user and app. The request MUST contain a name for the message collection. If successful, the container MUST return the ID of the newly-created message collection. Requests and responses to create a message collection use the following values: REST-HTTP-Method = "POST" REST-URI-Fragment = "/messages/" User-Id "/@self" REST-Query-Parameters = null REST-Request-Payload = Message-Collection-Name RPC-Method = "messages.create" RPC-Request-Parameters = ENCODE-RPC-PARAMETERS(CreateMessageCollection-Request-Parameters) Return-Object = Message-Collection-Id Message-Collection-Name = String

A request to create a message collection MUST support the Standard-Request-Parameters, and the following additional parameters: Name Type Description userId User-Id User ID of the person to associate the message collection with. Defaults to "@me", indicating the currently authenticated user. In the REST protocol, userId is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. name String The name of the message collection to create. In the REST protocol, the name is included in the REST-Request-Payload, rather than in the REST-Query-Parameters.

The Messages Service MAY support requests to update a Message or message collection for the currently authenticated user and app, such as marking a message as 'read'. Requests and responses to update a Message use the following values: REST-HTTP-Method = "PUT" REST-URI-Fragment = "/messages/" User-Id "/@self/" Message-Collection-Id "/" Message-Id REST-Query-Parameters = null REST-Request-Payload = Message RPC-Method = "messages.update" RPC-Request-Parameters = ENCODE-RPC-PARAMETERS(UpdateMessage-Request-Parameters) Return-Object = null Message-Id = Object-Id

A request to update a message MUST support the Standard-Request-Parameters, and the following additional parameters: Name Type Description userId User-Id User ID of the person who owns the Message. Defaults to "@me", indicating the currently authenticated user. In the REST protocol, userId is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. message Message The Message to update. In the REST protocol, the Message is included in the REST-Request-Payload, rather than in the REST-Query-Parameters.

The Messages Service MAY support requests to update a message collection for the currently authenticated user and app, such as renaming the message collection. Requests and responses to update a message collection use the following values: REST-HTTP-Method = "PUT" REST-URI-Fragment = "/messages/" User-Id "/@self/" Message-Collection-Id REST-Query-Parameters = null REST-Request-Payload = Message-Collection-Name RPC-Method = "messages.update" RPC-Request-Parameters = ENCODE-RPC-PARAMETERS(CreateMessageCollection-Request-Parameters) Return-Object = null Message-Collection-Name = String

A request to update a message collection MUST support the Standard-Request-Parameters, and the following additional parameters: Name Type Description userId User-Id User ID of the person to associate the message collection with. Defaults to "@me", indicating the currently authenticated user. In the REST protocol, userId is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. messageCollectionId Message-Collection-Id The ID of the message collection to update. In the REST protocol, message collection ID is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. name String The new name of the message collection to update. In the REST protocol, the name is included in the REST-Request-Payload, rather than in the REST-Query-Parameters.

The Messages Service MAY support requests to update a Message or message collection for the currently authenticated user and app, such as marking the message as 'read'. Requests and responses to update a Message use the following values: REST-HTTP-Method = "DELETE" REST-URI-Fragment = "/messages/" User-Id "/@self/" [ "/" Message-Collection-Id [ "/" Message-Id ] ] REST-Query-Parameters = null REST-Request-Payload = null RPC-Method = "messages.delete" RPC-Request-Parameters = ENCODE-RPC-PARAMETERS(DeleteMessage-Request-Parameters) Return-Object = null Message-Id = Object-Id

A request to delete a message or message collection MUST support the Standard-Request-Parameters, and the following additional parameters: Name Type Description userId User-Id User ID of the person to associate the message collection with. Defaults to "@me", indicating the currently authenticated user. In the REST protocol, userId is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. messageCollectionId Message-Collection-Id Optional. The ID of the message collection to delete. In the REST protocol, message collection ID is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters. messageId Object-Id Optional. The ID of the message to delete. In the REST protocol, message ID is specified in the REST-URI-Fragment, rather than in the REST-Query-Parameters.

The OpenSocial RESTful protocol is wire-compatible with Portable Contacts version 1.0 where applicable. Specifically, any compliant OpenSocial API Server that supports the People service is also a compliant Portable Contacts 1.0 Provider, because they are specified to use the same Authorization methods (OAuth), Additional Path Information, Query Parameters, and Contact Schema. The OpenSocial and Portable Contacts communities chose to wire-align these specifications in order to maximize widespread adoption of a single API for accessing people data. It is our intention to maintain this compatibility going forward, so long as it is feasible, and so long as the changes required are compatible with the goals and approach of this spec. Although Portable Contacts is an independent spec with a more limited scope than OpenSocial any proposed changes to either the OpenSocial RESTful Protocol or the Portable Contacts spec should be considered in the context of both communities, and SHOULD NOT break compatibility unless it is truly necessary, e.g. if the goals of the two communities diverge significantly in the future.

Harvard University IBM