opensocial-and-gadgets-spec@googlegroups.com

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

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.

Domain name examples use .

The grammatical rules in this document are to be interpreted as described in . 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 REST and RPC protocols to allow remote clients access to server side data. The data formats are independent of the protocols used in requests and common data types and formats are described in the Core Data Specification. Common data types for social applications are documented in the Social Data Specification.

The REST protocol 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. API Servers MUST support the REST protocol. 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, XML, and Atom / AtomPub, 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. Support for the ATOM format is being deprecated in the OpenSocial 2.0 release. Consumers should start migrating to using JSON or XML representations. 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. 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.

A REST request uses the following format: REST-Request = REST-HTTP-Method SP REST-Request-URI SP <any valid HTTP version identifier> CRLF { "HOST: " <any valid HTTP host> CRLF [ "Authorization: " Auth-Token CRLF ] [ "Content-Type: " Content-Type CRLF ] [ *(<a valid HTTP header not defined above> CRLF) ] } CRLF [ REST-Request-Payload ] For example, here is a REST request to retrieve information about a user: GET /api/people/@me/@self?fields=name HTTP/1.1 Host: api.example.org Authorization: hh5s93j4hdidpola Content-Type: application/json

Each REST resource defined in this document may specify the exact semantics of each method, but generally, "GET" is associated with retrieving a resource, "POST" is associated with creating a resource, "PUT" is associated with updating a resource, and "DELETE" is associated with deleting a resource. The following HTTP methods may be used for REST requests: REST-HTTP-Method = "GET" / "POST" / "PUT" / "DELETE" 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 that OpenSocial 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.

The request URI is composed from the base path, a URI fragment, and optional query parameters. REST-Request-URI = REST-Base-Path REST-URI-Fragment ["?" REST-Query-Parameters]

An OpenSocial REST server may choose to expose their REST endpoints in a "namespaced" way through use of a path. For example, the REST resource of "http://www.example.com/apis/people" would have a REST base path of "/apis", while "http://www.example.com/apis/opensocial-1.0/people" would correspond with the REST base path of "/apis/opensocial-1.0". REST-Base-Path = String

The URI fragment defines the exact resource that a request is targeting. Each service defines the format and possible values for the URI fragment based on the resources the service exposes. REST-URI-Fragment = String Each service type defines an associated partial URI format. The base URI for each service is found in the URI element associated with the service in the discovery document. Each service type accepts parameters via the URL path. Definitions are of the form:

{a}/{b}/{c}

Parameters must be filled in using left to right ordering. If a positional pattern is missing, no parameters to the right of that parameter may be filled in. For example, if the preceding pattern was used and only the value of the a parameter was known and set to @me, the complete URL would be expressed as:

[Discovery URI]/@me

Additional parameters for a REST request MAY be passed via the querystring portion of the request URI. REST-Query-Parameters = &ENCODE-REST-PARAMETER(k,v) This specification defines a function ENCODE-REST-PARAMETER, which is an alias for encoding a key/value pair. The PCT-ENCODE function is described in section 2.1 of . ENCODE-REST-PARAMETER(k,v) = PCT-ENCODE(k) "=" PCT-ENCODE(FLATTEN(v)) The FLATTEN function is also defined in this spec, and behaves in the following manner: If the argument supplied is an array of strings or numbers, the string representation of each array element is returned, with each element separated by a COMMA. If the argument supplied is a string or a number, the string representation of the argument is returned. The behavior of FLATTEN for input not explicitly covered here is undefined. This includes associative arrays, or nested arrays. Here is an example of a REST request URL with query parameters. Note that the fields parameter demonstrates a flattened array: http://www.example.com/opensocial/rest/people/@me/@self?fields=name,gender&format=json

A REST request MAY carry a payload, such as an object to create on the server. Each service defines which requests support a payload and the format of the payload.

A REST response uses the following format: HTTP/1.x HTTP-Status-Code [ "Content-Type: " Content-Type ] [ REST-Response-Payload ]

A REST request MAY contain a payload. Each service method defines the object that is included as the Return-Object. The payload uses the following format: REST-Response-Payload = [ REST-XML-Response-Payload | REST-JSON-Response-Payload ] REST-XML-Response-Payload = "<response xmlns='http://ns.opensocial.org/2008/opensocial'>" Return-Object "</response>" REST-JSON-Response-Payload = Return-Object / (<"> "error" <"> ":" RPC-Error) Discussion

The RPC protocol supports the same data and operations as the RESTful API in a form that is more natural for the JSON data format. Any batch of RPCs should be programatically convertible to a sequence or batch of RESTful calls and maintain the same semantics, any exception to this will be called out explicitly. API Servers MAY support the RPC protocol. The RPC protocol shares the following with the RESTful protocol: The JSON/XML format of the OpenSocial data types such as Person, Activity, Group, AppData are identical. HTTP status codes are used to represent common error cases where applicable. is supported for authentication and authorization in addition to other authorization schemes a container may choose to support. A single OAuth token can be used for a batch of operations or each operation can specify its own OAuth token. Concurrency control is optional. The RPC protocol differs from the RESTful protocol in the following ways: Conforms to the specification All structural elements in the protocol are represented using the JSON or XML notation. Batch support is required. HTTP is used primarily as a transport and not to indicate the semantics of the request. Automated discovery happens in two steps. XRDS can be used to discover the RPC endpoint. The service can then be introspected by executing a request to the system.listMethods method to discover the list of available services and operations using conventions defined by XML-RPC Introspection. In general it is expected that a large percentage of consumers will bypass automated discovery and rely on simply hardcoding references to the endpoints of various popular containers.

Containers MUST give access to the RPC services using a URL addressing scheme to invoke a single RPC via HTTP GET. This encoding can also be used to support RPC execution via form posts including file-uploads as parameters to RPCs. It is recommended that only services that are idempotent are exported in this manner. Containers MUST use the following canonical transformation between the RPC structure and its URL encoding: The RPC method is defined by the 'method' query parameter The RPC id is defined by the 'id' query parameter All other query parameters are assumed to belong to the RPC params element and are encoded from JSON using <field path dot notation>=<scalar value> | <comma separated array of scalars>. When a field represents an array of non-scalars then elements of the array are identified by enclosing the index in parenthesis. Strings which match [0-9]+ MUST be single-quoted, Strings which match [A-Za-z_]+ MUST be unquoted, all other strings retain their original quoting. The following provides some examples of mapping JSON objects to URL Parameters: JSON Object URL Parameter { "field" : "value" }field=value { "field" : [1,2,3,4,5]}field=1,2,3,4,5 { "field" : "12" }field='12' { "field" : [identifier,anotheridentifier]}field=identifier,anotheridentifier { "field" : ["value","another value"]}field=value,"another value" { "field" : ['value','another value']}field=value,'another value' { "field" : { "nested" : "value" }}field.nested=value { "field" : [{ "nested1" : "value1" }, { "nested2" : "value2" }]}field(0).nested1=value1&field(1).nested2=value2 For example, given the following RPC-Request-Payload: { "method" : "people.get", "id" : "myfriends", "params": {"userId" : "@me", "groupId" : "@friends" } } The corresponding URL is: http://api.example.org/rpc?method=people.get&id=myfriends&params.userId=@me&params.groupId=@friends In situations where containers support the URL Addressing scheme to perform an RPC the container MAY return arbitrary content types in the response other than application/json. The system.methodHelp operation relies on this to provide browseable documentation.

An RPC request uses the following format: RPC-Request = "POST /" RPC-Base-URL " HTTP/1.1" "HOST" <any valid HTTP host> "Authorization: " Auth-Token "Content-Type: " Content-Type RPC-Request-Payload For example, here is a RPC request to retrieve information about a user: POST /rpc HTTP/1.1 Host: api.example.org Authorization: hh5s93j4hdidpola Content-Type: application/json { "method" : "people.get", "id" : "myself" "params" : { "userId" : "@me", "groupId" : "@self" } }

The RPC Base URL is defined in the XRDS file.

RPC requests MAY batch multiple procedure calls into a single HTTP request. Therefore, the payload of an RPC request can container a JSON array of procedure calls, or a single procedure call: RPC-Request-Payload = RPC-Batch-Payload / RPC-Single-Payload RPC-Batch-Payload = "[" #RPC-Single-Payload "]" RPC-Single-Payload = "{" <"> "method" <"> ":" <"> RPC-Method <"> "," <"> "id" <"> ":" <"> Request-ID <"> "," [ <"> "params" <"> ":" RPC-Request-Parameters ] "}" Note that the "json-rpc" property defined in JSON-RPC is not passed in the request but requests MUST be interpreted as if "json-rpc" : "2.0" was supplied. If a method call has no parameters, or only default values are required, the "params" field can be omitted completely. Here is an example of a RPC request with a batch of procedure calls in the payload: POST /rpc HTTP/1.1 Host: api.example.org Authorization: hh5s93j4hdidpola Content-Type: application/json [ { "method" : "people.get", "id" : "myself", "params" : { "userId" : "@me", "groupId" : "@self" } }, { "method" : "people.get", "id" : "myfriends", "params" : { "userId" : "@me", "groupId" : "@friends" } } ] Note that multiple authorization tokens MAY be used in a single batch request. The following example contains an authorization token as an HTTP header in the request, which is overridden by an authorization token provided in the 'auth' property in the second request object of the batch. In this example, assume that Alice doesn't have access to Bob's profile, so her authorization token is not sufficient to access his information. The client making the request has an authorization token for Bob's profile, so the client can include this token to retrieve his information as well. For more information on authentication and authorization, see Security. POST /rpc HTTP/1.1 Host: api.example.org Authorization: <1st Auth token> Content-Type: application/json [ { "method" : "people.get", "id" : "profileOfAlice" "params: { "userId" : "09737549474", } }, { "method" : "people.get", "id" : "profileOfBob", "params: { "userId" : "34906734059", "auth" : "<2nd Auth token>" } } ]

The value of the "method" field in an OpenSocial RPC request uses a format of "<service-name>.<operation>". <service-name> is a string [A-Za-z0-9_]+ that identifies one of the services listed in [Services] and <operation> is a string [A-Za-z0-9_]+ that identifies an operation supported by that service. RPC-Method = <"> Service-Name "." Method-Name <"> Service-Name = String Method-Name = String All OpenSocial services MUST expose a "get" operation. Operations with the names get, create, update and delete should map to the HTTP equivalent operations in the RESTful protocol of GET, PUT, POST & DELETE. Available methods can be determined by calling the system.listMethods method.

Parameters can be passed to RPC methods in the request payload as a JSON object as described in Appropriate values for RPC request parameters can be determined by calling the system.methodSignatures method. Here is an example of an RPC request payload with procedure-specific parameters (userId, groupId) and standard OpenSocial parameters: { "method" : "people.get", "id" : "myself" "params" : { "userId" : "@me", "groupId" : "@self", "fields" : "name, gender", "format" : "json" } } This specification defines a function ENCODE-RPC-PARAMETER which is an alias for the JSON encoding process. This function takes a key and value as arguments, where the key must be a string, and the value must have a valid JSON encoding. ENCODE-RPC-PARAMETER(k,v) = "{" <"> k <"> ":" JSON-ENCODE(v) "}")

An RPC response uses the following format: HTTP/1.x 207 Multi-Status "Content-Type: " Content-Type RPC-Response-Payload

RPC responses MAY contain results from multiple procedure calls, if the corresponding HTTP request contained a RPC-Batch-Payload. The batch response elements MUST be returned in the same order as the corresponding batch request elements and the "id" property of the corresponding request in the batch request MUST be carried over to the response. If processing of the entire batch fails, as opposed to a single request within the batch, then the returned value is a single RPC-Error object with the appropriate error message and code. The response payload for a single procedure call MUST contain an 'id' property to correlate the response with a request. On success, the payload MUST contain a 'result' property. On failure, the payload MUST contain an 'error' property. Each service method defines the object that is included as the Return-Object. RPC-Response-Payload = RPC-Batch-Payload / RPC-Single-Payload RPC-Batch-Payload = RPC-Error / ("[" #RPC-Single-Payload"]") RPC-Single-Payload = "{" <"> "id" <"> ":" <"> Request-ID <"> "," ( (<"> "result" <"> ":" <Return-Object>) / (<"> "error" <"> ":" RPC-Error) ) "}" The following examples illustrate how success and failure are represented in responses to batch requests. Batch successful, all procedure calls successful: [ { "id" : "myself", "result" : { ... } }, { "id" : "myfriends", "result" : { ... } } ] Batch successful, some procedure calls successful while some fail: [ { "id" : "myself", "result" : { ... } }, { "id" : "myfriends", "error" : { ... } } ] Batch successful, all procedure calls fail: [ { "id" : "myself", "error" : { ... } }, { "id" : "myfriends", "error" : { ... } } ] Batch fails: { "error" : { ... } }

An error object MUST contain a 'code' property to indicate the actual error that occurred and MAY contain a 'message' property describing the error. Additional information may be returned in the 'data' property, as defined by the procedure. RPC-Error = "{" [ <"> "message" <"> ":" <"> string <"> "," ] [ <"> "data" <"> ":" <any JSON object> "," ] <"> "code" <"> ":" integer "," "}" A common set of error codes are used to represent failure modes that apply generally to operations and so are reserved for use by this specification. Code Meaning -32700 (Parse error) Invalid JSON. An error occurred on the server while parsing the JSON text. -32600 (Invalid Request) The received JSON not a valid JSON-RPC or batch of JSON-RPCs. -32601 (Method not found) The requested remote-procedure does not exist / is not available. -32602 (Invalid params) Invalid method parameters. -32603 (Internal server error) Internal server error. -32099..-32000 Reserved for implementation-defined server-errors. 401 (Unauthorized) Access token does not grant access to the resource, 404 (Not Found) The requested resource was not found. 409 (Conflict) The requested update conflicts with a prior change. 0-1000 Reserved for future use by this specification. Here is an example of an unsuccessful RPC response payload: { "id" : "myself" "error" : { "code" : 401 "message" : "The authorization token does not provide access to the requested resource." } }

OpenSocial Containers MUST support TLS 2.0 / SSL connections for sensitive data since OAuth on its own does not provide encryption or message body integrity checking. Note that TLS 2.0/SSL is required with many scenarios in the OAuth 2.0 specification.

Core Gadget Servers MUST support Open Authorization 1.0a but SHOULD use appropriate policies to determine which operations are allowed on a per-consumer and per-user basis. When OAuth 1.0a is used for authorization on a single RPC, the OAuth signature uses the URL Addressing representation of the request without the authorization parameter, in order to calculate the signature base string.

Discussion Core Gadget Servers MUST support the authorization server, resource server and client roles defined in section 1.1 of the Open Authorization 2.0 specification . A Core Gadget Server MUST provide authorization, token issuance and resource access endpoints per the OAuth 2 specification. A Core Gadget Server MUST implement the authorization code and client credential types described in section 4 of the Open Authorization 2.0 specification. Core Gadget Servers SHOULD implement the implicit grant type. Core Gadget Servers MAY implement the refresh token pattern described in section 1.5 of the OAuth 2.0 specification.

For 2 party (client credential) OAuth requests, if a Core Gadget Server 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 along with the OAuth parameters as a query fragment. Often times, the value for the xoauth_reqeustor_id will be set to the e-mail address of the user, on who's behalf the Core Gadget Server is making the call. Core Gadget Servers SHOULD only provide the xoauth_requestor_id if the user has given prior consent to the operation or class of operations being done on their behalf. Core Gadget Servers MUST either honor the parameter or ignore it as if it were not provided.

OpenSocial Containers may wish to restrict requests from unknown clients and require gadget registration, in order to mitigate risk. OpenSocial Containers SHOULD document how to register a gadget with the OpenSocial Container in order to obtain a client identifier and client secret. This is typically done through a web page, although the exact method is left to the specific implementation. Note that per the security considerations mentioned in the OAuth 2.0 specification, client secrets should not be issued to untrusted clients. Discussion OpenSocial Containers SHOULD document how to store client identifiers and client secrets on the server in order for a gadget running locally to access remote data in another server.

OpenSocial Containers SHOULD document how the OpenSocial Container handles redirection when authenticating a user and obtaining authorization for a gadget. Note that this is a potential vector for phishing if the user is required to enter their credentials. Normally, for three-party OAuth exchanges, the OpenSocial Container will provide a web page to collect authentication and scoped authorization information, although the exact method is left to the specific implementation.

OpenSocial Containers SHOULD base their security decisions on the type of client in use; a generally available desktop client, for example, cannot effectively protect a client secret that is installed with each client (implicit grant). The security of communications with a two-party partner service, on the other hand, is dependent on the effectiveness of that service's security procedures (client credential grant). The security of communications with a three party service, involving a registered server, a client/gadget and the OpenSocial Container, should follow the security guidelines outlined in the OAuth 2.0 security considerations document (authorization grant). OpenSocial Containers SHOULD provide an ability to scope the authorization to data as narrowly as possible (e.g., allow reading but not writing if a client only performs reads). Discussion

OpenSocial Containers SHOULD issue access tokens with short expiration times to limit the scope of security breaches due to stolen access tokens. The token expiration policy is left to the specific implementation and may vary depending on the client requesting the token. Expiration times of 1 hour or less, and tokens with limited scope may be used with less trusted clients while expiration times of several hours and tokens with increased scope may be used for more trusted clients. An OpenSocial Container SHOULD document (at least for administrators) how to configure token scopes and expiration times if these values are configurable.

Each API call from a gadget to the Core Gadget Server has a request context that usually includes authentication and authorization information. Typically, the context information includes the requester id (the user initiating the request) and app Id (the application, or whatever is acting as the user's agent). It may include other core container-specific information. The requesting application and user may be implied through the OAuth tokens, or may be provided explicitly in the xoauth_requestor_id optional parameter. Request contexts can also include things such as cookies, URI parmaters, client SSL certificates and other information.

An OpenSocial Container may accept requests with no authentication or authorization information for public data. A container may provide a public version (e.g., of a profile) if no authorization information is provided. Note that the data provided for a given RESTful URI MAY vary per requestor or application. The data returned from a resource URI is "the view of the information available to the current requestor/application 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 authorization context.

Discussion Content Upload is a generic mechanism to allow for a standard way to upload content. This mechanism MAY be used to upload to an existing Album, MediaItem endpoint, or where appropriate. In most scenarios an uploaded content is associated with creation of an entity. Upload of content routinely causes the creation of the entity. For example, uploading a photo causes the container to create a new media item. The application can then update that MediaItem and set attributes via a second request at some later time. The requests look like: Step 1: Upload Photo Step 2: Update Photo attributes (title, description, etc.) The two step request process is illustrated below. Step 1: Upload the image in the album.

Request POST /album/112233?mediaType=IMAGE HTTP/1.1 <usual headers> Accept-Type: application/xml Content-Type: image/gif Content-Length: length GIF89a....<binary data>

Response <feed xmlns="http://www.w3.org/2005/Atom" xmlns:ossearch="http://a9.com/-/spec/opensearch/1.1/"> <author><uri>urn:guid:example.org:33445577722</uri></author> <link rel="next" href="http://api.example.org/..." /> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:osapi="http://opensocial.org/2008/opensocialapi"> <content type="application/xml"> <mediaitem xmlns="http://ns.opensocial.org/2008/opensocial"> <id>223344</id> <type>IMAGE</type> </mediaitem> </content> <title /> <updated>2008-10-24T20:30:40.500Z</updated> <author /> </entry> </feed>

Step 2: PUT MediaItem details to MediaItem (id:223344) Note: response includes "caption" in addition to "title". Caption is being deprecated in the 1.0 data format and will be removed entirely in a future version of the spec.

Request <entry xmlns="http://www.w3.org/2005/Atom" xmlns:osapi="http://opensocial.org/2008/opensocialapi"> <content type="application/xml"> <mediaitem xmlns="http://ns.opensocial.org/2008/opensocial"> <id>223344</id> <type>IMAGE</type> <url>http://cdn.example.org/223344.gif</url> <title>Lena</title> </mediaitem> </content> <title /> <updated>2008-10-24T20:30:40.500Z</updated> <author /> </entry>

Response <feed xmlns="http://www.w3.org/2005/Atom" xmlns:ossearch="http://a9.com/-/spec/opensearch/1.1/"> <author><uri>urn:guid:example.org:33445577722</uri></author> <link rel="next" href="http://api.example.org/..." /> <ossearch:totalResults>100</ossearch:totalResults> <ossearch:startIndex>1</ossearch:startIndex> <ossearch:itemsPerPage>10</ossearch:itemsPerPage> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:osapi="http://opensocial.org/2008/opensocialapi"> <content type="application/xml"> <mediaitem xmlns="http://ns.opensocial.org/2008/opensocial"> <id>223344</id> <type>IMAGE</type> <url>http://cdn.example.org/223344.gif</url> <title>Lena</title> </mediaitem> </content> <title /> <updated>2008-10-24T20:30:40.500Z</updated> <author /> </entry> </feed>

The response indicates that the media item was updated.

The shortcut upload mechanism is OPTIONAL. This two step process shown above can be merged into one by a single POST request with the content type set to the item being uploaded. The POST URL can optionally pass the attributes. The Accept-type indicates the format of the response expected.

Request POST /album/112233/mediaitem/?title=Lena&type=IMAGE HTTP/1.1 <usual headers> Accept-Type: application/json Content-Type: image/gif Content-Length: length GIF89a....<binary data>

Response { "startIndex" : 1, "itemsPerPage" : 1, "totalResults" : 1, "entry" : { "id" : "223344", "title" : "Lena", "type" : "IMAGE", } }

A container MAY choose to support file uploads from browsers to the RPC endpoint and have the uploaded files be passed as parameters to the RPC. This is achieved by browsers posting a form which contains the files to the endpoint and including a form-parameter called "request" which contains the form-encoded RPC request. The form input element names for the uploaded files will be bound to the corresponding parameter names on execution. A multipart form-data request mechanism ("Content-Type: multipart/form-data") enables upload of content. Such a request has the POST body segmented into several sections (fields) with each field identified by a name. The field name "request" is reserved and contains request operation details (same as the contents on the POST body in the vanilla POST operation). The fields with any other name contain content to be uploaded to the OpenSocial container. To allow batching and multiple file uploads in a single call, multiple fields (identified with unique field names) are allowed. The OpenSocial request can refer to the content being uploaded by setting the URL to "@field:<fieldname>". The container may host the uploaded file and replace the URL field with a fully qualified URL for future access. For a successful upload, the response code of the request will be associated with the response code of the action request on the resource. However, in case of a failure due to a file size exceeding limits, an error code of 413 ("Request Entity Too Large") MUST be returned. The requested action associated with the file upload MUST NOT be executed.

Example: <usual headers> Content-type: multipart/form-data; boundary=------------abcdef012345xyZ Content-length: <contentLength> ------------abcdef012345xyZ Content-Disposition: form-data; name="request" [{ "method":"activities.create", "params": { "userId":["@viewer"], "groupId":"@self", "appId":"@app", "activity": { "title": "hello world!", "mediaItems": [ { "mimeType":"image", "url":"@field:image1" } ] } }, "id":"key" } ------------abcdef012345xyZ Content-Disposition: form-data; name="image1" GIF89....<image data> ------------abcdef012345xyZ

A string identifying a request.

A string used to authenticate a request.

A string used to identify the type of content in a request or response.

The actual content included in the response. Each service method defines the object that is included as the Return-Object.

A collection of keys that identify resources that should have their cached version refreshed. Keys can either be URLs or IDs of objects to be refreshed. Keys that refer to URLs MUST include a protocol prefix (e.g. 'http://') so they can be distinguished from ids. Each request accepts a repeated group of keys. Invalidation-Key-List = "{" <"> "invalidationKeys" <"> ":" "[" #Invalidation-Key "]" "}" Invalidation-Key = <any valid URL> / Object-Id

Status Code Description 400 BAD REQUEST OpenSocial application servers MUST return 400 BAD REQUEST under any one or more of the following conditions: Invalid request URI Invalid HTTP Header Receiving an unsupported, nonstandard parameter A parameter is repeated Receiving an invalid HTTP Message Body 401 UNAUTHORIZED OpenSocial container servers MUST return 401 UNAUTHORIZED when receiving an OAuth request for a protected resource and the request is either Missing OAuth authorization credentials as described in for OAuth 1.0a or in for OAuth 2.0 requests. If the request already included authorization credentials, the 401 response indicates that the request has been refused for those credentials. A 401 response MUST include a WWW-Authenticate header field indicating the request MAY present an OAuth token for the container server's realm. Example: WWW-Authenticate: OAuth realm="http://sp.example.com/" Discussion 403 FORBIDDEN The server understood the request but is refusing to fulfill it. Authorization will not help. The current authorization context does not allow the request. Also used in case where OAuth authorization credentials are present, but the user identity is not authorized to access the protected resource. Discussion 404 NOT FOUND The server has not found a resource (such as a feed or entry) that matches the request URI. 405 METHOD NOT ALLOWED The method specified in the Request-Line is not allowed for the resource identified by the Request-URI. The response MUST include an Allow header containing a list of valid methods for the requested resource. 409 CONFLICT The request could not be completed due to a conflict with the current state of the resource. This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request. The response body SHOULD include enough information for the user to recognize the source of the conflict. Ideally, the response entity would include enough information for the user or user agent to fix the problem; however, that might not be possible and is not required. Conflicts are most likely to occur in response to a PUT request. For example, this code can be used for a limit exceeded error as well as conflicting updates. See the error message for more information. 500 INTERNAL SERVER ERROR Internal error. This is the default code that is used for all unrecognized errors. 501 NOT IMPLEMENTED The request was valid but has not been implemented by the provider. A container SHOULD return 501 NOT IMPLEMENTED when receiving a request for an OPTIONAL/MAY feature that the container does not implement.

All requests MUST support the following parameters:

Request-Parameter-UpdatedSince-Value = When specified the container should only return items whose updated date & time is equal to or more recent then the specified value. The value MUST be a valid (e.g. 2008-01-23T04:56:22Z).

JSON is the standard format adopted by OpenSocial. Request-Parameter-Formet-Value = "json" / "xml" / "atom" Specifies the desired return encoding of the request. Must be one of "json", "xml", or "atom".

All requests that return a Collection of objects MUST support the following parameters:

Request-Parameter-Count-Value = number The page size for a 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.

Request-Parameter-FilterBy-Value = string For a collection, return entries filtered by the given field name.

Request-Parameter-FilterOp-Value = "contains" / "equals" / "startsWith" / "present" The operation to use when filtering a collection by a field specified in 'filterBy', defaults to "contains". Valid values: Return elements where filterValue appears somewhere in the element's filterBy field value. Return elements where filterValue exactly matches the element's filterBy field value. Return elements where filterValue exactly matches the first N characters of the element's filterBy field value, where N is the length of the filterValue string. Return elements where the element's filterBy field value is not empty or null.

Request-Parameter-FilterValue-Value = string The value to use when filtering a collection. For example: { ... "filterBy" : "name", "filterOp" : "startsWith", "filterValue" : "John" ... } returns all items whose name field starts with John. Johnny and John Doe would both be included.)

Request-Parameter-SortOrder-Value = "ascending" / "descending" Can either be 'ascending' or 'descending', defaults to ascending. Used to sort objects in a collection.

Request-Parameter-StartIndex-Value = number Index into a paged collection.

Behavior of query parameters to determine if two people are friends (important part is the query string): /people/@me/@self?filterBy=@friends&filterOp=contains&filterValue=<someUserId>

This will return nothing if the other ID is not a friend, the current user if the two are friends. filterValue may take a specific person identifier of @owner or @viewer.

To determine the mutual friends between two people (important part is the query string): /people/@me/@friends?filterBy=@friends&filterOp=contains&filterValue=<someUserId>

This will return the set of mutual friends between the current user and someUserId. filterValue may take a specific person identifier of @owner or @viewer. 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".

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 at http://xrds-simple.net/core/1.0/; in a nutshell: Client GETs {container-url} with Accept: application/xrds+xml Container responds with either an X-XRDS-Location: header pointing to the discovery document, or the document itself. If the client received an X-XRDS-Location: header, follow it to get the discovery document. Once the client has the XRDS document, they have the complete set of services supported by that service. All OpenSocial service types declare the base URI in the XRDS URI element. Each service type declares the root URI for the service. Service specific parameters are passed to each endpoint using a fixed URI format. This format is defined by each service. 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)" version="2.0"> <Type>xri://$xrds*simple</Type> <Service> <Type>http://ns.opensocial.org/2008/opensocial/people</Type> <URI>http://api.example.org/people</URI> </Service> <Service> <Type>http://ns.opensocial.org/2008/opensocial/groups</Type> <URI>http://api.example.org/groups</URI> </Service> <Service> <Type>http://ns.opensocial.org/2008/opensocial/activities</Type> <URI>http://api.example.org/activities</URI> </Service> <Service> <Type>http://ns.opensocial.org//2008/opensocial/appData</Type> <URI>http://api.example.org/appData</URI> </Service> <Service> <Type>http://ns.opensocial.org/2008/opensocial/cache/invalidate</Type> <URI>http://api.example.org/cache/invalidate</URI> </Service> <Service> <Type>http://ns.opensocial.org/2008/opensocial/messages</Type> <URI>http://api.example.org/messages</URI> </Service> <Service> <Type>http://ns.opensocial.org/2008/opensocial/albums</Type> <URI>http://api.example.org/albums</URI> </Service> <Service> <Type>http://ns.opensocial.org/2008/opensocial/mediaItems</Type> <URI>http://api.example.org/mediaItems</URI> </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.

The cache service is used to manage the resources cached by the container for a given application.

An application can execute an invalidation request as a POST to the Cache service. Requests include a list of URLs associated with resources that should have their cache invalidated. Invalidation keys can include the URL of the gadget spec, associated message bundle files, static resources (e.g. images, CSS), or remote content fetched via osapi.http. Containers MUST support the invalidation endpoint even if they do not perform any caching and MUST provide an entry for it in their XRDS. To invalidate content a developer's backend notifies the container of the content it wishes to invalidate by making a 2-legged OAuth call to the Cache service with one or many keys to be invalidated. The consumer key in the 2-legged OAuth call is used by the container to identify the calling application. Containers MAY reject invalidation requests for policy reasons. Containers MAY continue to serve content that has already been invalidated until the container is able to successfully fetch a replacement from it original source. Response codes have the following meanings: 200 - Success, all invalidations processed successfully. 403 - Forbidden because authentication failed. 409 - The request was partially processed, the set of invalidation keys that were not honored MUST be included in the response body in the format the request was made. XRDS Type: http://ns.opensocial.org/2008/opensocial/cache/invalidate Requests and responses for the Cache service's Invalidate method use the following values: REST-HTTP-Method = "POST" REST-Request-URI = "/cache/invalidate" REST-Request-Parameters = null REST-Request-Payload = Invalidation-Key-List RPC-Method = "cache.invalidate" RPC-Request-Parameters = Invalidation-Key-List Return-Object = [ Invalidation-Key-List ] Here is an example that invalidates the cache for the gadget spec and message bundle of an application using REST: POST /api/rest/cache/invalidate HTTP/1.1 Host: api.example.org Authorization: hh5s93j4hdidpola Content-Type: application/json { "invalidationKeys" : [ "http://www.myapp.com/gadgetspec.xml", "http://www.myapp.com/messagebundle.xml" ] } Here is an example illustrates how information for users and a static resources can be invalidated using RPC. The example shows how to specify a user with a global ID (i.e. an ID which includes the domain of the container) or a relative ID. The static resource in this example is the gadget spec itself. POST /api/rpc Host: api.example.org Content-Type: application/json { "method" : "cache.invalidate", "params" : { "invalidationKeys" : [ "example.org:12345", "example.org:4567", "3456778", "http://www.myapp.com/gadgetpec.xml" ] } }

The System service is used to introspect the API server for the set of available services and operations and for metadata about those services. The System service only supports the RPC protocol.

Containers MUST implement this operation which takes no parameters and returns an array of all methods supported by the endpoint including the system methods. Requests and responses to the System service's List Methods method use the following values: RPC-Method = "system.listMethods" RPC-Request-Parameters = null Return-Object = [ #String ] Here's an example using RPC: POST /api/rpc Host: api.example.org Content-Type: application/json { "method" : "system.listMethods", "params" : {} } A container which only supports read access to people and read and create access for activities would include the following Return-Object in the response: [ "people.get", "activities.get", "activities.create", "system.listMethods", "system.methodSignatures", "system.methodHelp" ]

Containers MUST implement this operation that returns a method signature describing the types of the parameters, their default values and the type of the return value for a given operation. Note that this scheme does not match that used for XML-RPC definition of method signatures which only specifies a mapping for positional parameters. Type definitions used here match the scheme used in the OpenSocial Javascript API. RPC-Method = "system.methodSignatures" RPC-Request-Parameters = { <"> "methodName" <"> ":" String "}" Return-Object = Method-Signatures Method-Signatures = "{" <"> "return" <"> ":" ( String-Value / String-List ) "," #Parameter-Spec "}" Parameter-Spec = Param-Name ":" "{" <"> "type" <"> ":" ( String-Value / String-List ) "," [ <"> "default" <"> ":" ( "null" / String-Value / String-List ) "," ] [ <"> "required" <"> ":" <"> false <"> ] "}" Param-Name = String-Value String-Value = <"> String <"> String-List = "[" #String-Value "]" The "return" field indicates the type of the result. If the service can return more than one type then the value is an array of the possible return types. Each named field in the response maps to a parameter of the operation and contains information about the types and values accepted for that parameter. The existence of "default" in the parameter detail indicates the parameter has a default value. The value of a default may be null which means that its not introspectable and usually means that it is some complex derivation. Parameters are assumed to be required unless otherwise indicated by the existence of the "required" field with a value of false. Here is an example of a request for the method signature of people.get. POST /api/rpc Host: api.example.org Content-Type: application/json { "method" : "system.methodSignatures", "params" : { "methodName" : "people.get" } } Here is the response to a request for the method signature of people.get. { "return" : ["opensocial.Person", "Array.<opensocial.Person>"], "auth" : { "default" : null, "type" : "AuthToken" }, "userId" : { "default" : "@me", "type" : ["String", "Array.<String>"] }, "groupId" : { "default" : "@self", "type" : "String" }, "fields" : { "default" : ["id","name","thumbnailUrl","profileUrl"], "type" : "Array.<String>" }, "count" : { "type" : "int", "required" : false }, "startIndex" : { "type" : "int", "required" : false } }

Containers MAY implement this operation that returns a textual description of the operation identified by the methodName parameter. A container can choose to return either plaintext or HTML as the response. RPC-Method = "system.methodHelp" RPC-Request-Parameters = { <"> "methodName" <"> ":" <"> String <"> "}" Return-Object = String Here's a request to get the help content for the people.get method. POST /api/rpc Host: api.example.org Content-Type: application/json { "method" : "system.methodSignatures", "params" : { "methodName" : "people.get" } } The response might be something like: Used to fetch profile information about people.

OpenSocial containers MAY support concurrency control to prevent multiple clients from overwriting each other's data. The mechanism supported by OpenSocial uses the standard HTTP/AtomPub optimistic concurrency mechanism based on ETags (see section 9.5 of for details; the same mechanism applies regardless of the data format used for the body of the PUT).

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.

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.

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.

This example demonstrates the use of etags to detect an incompatible update to the profile of the user identified in the auth token. The request is attempting to update the 'books' field and passes the etag the client received when it retrieved the person object prior to update. The etag is added to the update request shown below but an intervening update from another client has made the change incompatible and so the update is rejected. Notes: The error code 409 is the HTTP Conflict status code. The error object "data" field contains a limited representation of the latest version of the person object including an up-to-date etag value. Containers MAY omit this data from conflict error responses.

POST /rpc HTTP/1.1 Host: api.example.org Authorization: <auth token> Content-Type: application/json { "method" : "person.update", "id" : "setMyData" "params: { "userId" : "@me", "groupId" : "@self", "person" : { "etag" : "767ffdef7", "books" : ["The Prince", "Hotel New Hampshire"] } } } HTTP/1.x 207 Multi-Status Content-Type: application/json { "id" : "myself", "error" : { "code" : 409 "message" : "Conflict detected", "data" : { "etag" : "8543de12", "books" : ["The Right Stuff", "About a boy"] } } }

Harvard University IBM Google NewBay Software Kaiser Permanente, for Health Level Seven Microsoft Google Twitter Pownce Flickr ma.gnolia Google Twitter six apart Yedda ma.gnolia Jaiku Yahoo ! Facebook Microsoft

Discussion Discussion

<?xml version="1.0" encoding="utf-8"?> <xs:schema xmlns:tns="http://ns.opensocial.org/2008/opensocial" elementFormDefault="qualified" targetNamespace="http://ns.opensocial.org/2008/opensocial" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="response"> <xs:complexType> <xs:choice> <xs:element name="entry" type="xs:anyType" /> <xs:group ref="tns:collection" /> <xs:element name="invalidationKeys" type="tns:InvalidationKeys" /> </xs:choice> </xs:complexType> </xs:element> <xs:group name="collection"> <xs:sequence> <xs:element name="itemsPerPage" type="xs:int" /> <xs:element name="startIndex" type="xs:long" /> <xs:element name="totalResults" type="xs:long" /> <xs:element name="filtered" type="xs:boolean" /> <xs:element name="sorted" type="xs:boolean" /> <xs:element name="updatedSince" type="xs:boolean" /> <xs:element name="list" type="xs:anyType" minOccurs="0" maxOccurs="1" /> <xs:element name="entry" type="xs:anyType" minOccurs="0" maxOccurs="unbounded" /> </xs:element> </xs:sequence> </xs:group> <xs:complexType name="InvalidationKeys"> <xs:sequence> <xs:element name="invalidationKey" type="xs:string" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> </xs:schema>