OpenSocial Data Pipelining Specification v0.9

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

Data Pipelining is a declarative syntax for defining the data you want the container to provide to you for processing. Examples would be <os:DataRequest method="people.get" userId="@viewer"/> or <os:HttpRequest href="http://www.example.com/api">. The <os:DataRequest> element provides access to OpenSocial data, and the <os:HttpRequest> element provides access to content from any HTTP endpoint. Several convenience elements provide simplified access to OpenSocial data. The data that is retrieved will be available in three contexts: Proxied content requests. This data will be POSTed to the developer party server with requests for proxied content. OpenSocial Templates. The data will be available as named variables in OpenSocial templates. JavaScript. This data will be available in the JavaScript API. Developers will insert the following <os:*> namespaced tags within a <Content> block to specify what data should be provided to the gadget. RESTful call equivalents: <os:DataRequest> - request to OpenSocial data, including person data, activity data, and any container-specific endpoints <os:HttpRequest>, equivalent to gadgets.io.makeRequest This is a call to an arbitrary URL. <os:PeopleRequest> - convenience element to get profile information for a group or list of people <os:ViewerRequest>, <os:OwnerRequest> - convenience elements to get the viewer or owner's profile <os:ActivitiesRequest> - convenience element to get activities

<Content type="html"><![CDATA[ <script xmlns:os="http://ns.opensocial.org/2008/markup" type="text/os-data"> <os:DataRequest key="vwr" method="people.get" userId="@viewer" fields="name,birthday"/> <os:ViewerRequest key="vwr2" fields="name,birthday"/> <os:HttpRequest key="mydata" href="http://example.com/api"/> </script> ... HTML content here ... ]]></Content> Note that we only have equivalents for REST calls that get data - calls that update data cannot be safely used in Data Pipelining. Data Pipelining creates a new feature name for use in the Gadgets Specification: opensocial-data. When data pipelining elements are embedded in type=@html, the Module must contain this XML:

All XML tags MUST have an @key string attribute. This is used to identify the data in the response back. Calls with corresponding REST APIs have a 1:1 mapping between the XML attributes and the RESTful API parameters. See the OpenSocial RESTful Protocol for an overview of the REST calls.

Request to get OpenSocial data, including person data, activity data, and any container-specific endpoints. Attributes @key {string} @method {string} The name of the REST endpoint and operation called. Implementations MUST support "people.get" and "activities.get", and MUST NOT support ".update", ".create", or ".delete" operations. All other attributes will be passed as string parameters to the endpoint. See the OpenSocial RESTful protocol for information on the parameters available for each endpoint. Returns JSON object (typically, an array) representing the results of invoking the endpoint.

Example: <os:DataRequest key="PagedFriends" method="people.get" userId="@owner" groupId="@friends" startIndex="40" count="20"/>

Request for arbitrary URL data, equivalent to gadgets.io.makeRequest(). This tag has additional attributes to match the functionality of gadgets.io.makeRequest. Containers will typically cache the results of these requests; see the Gadget section 4.2 and OpenSocial section 4.2.6 specifications for more information. Attributes @key {string} @href {string} The URL to send a request to. @params {string} Additional URL parameters, of format "a=b&c=d". Optional. @method {string} HTTP method to use, one of "get" or "post". Defaults to "get". Optional. If method is "post", then the "@params" parameters are sent as POST content with a content type of "application/x-www-form-urlencoded". If method is "get", then the params are appended to the URL. There is no ability to set arbitrary POST content, this just determines whether the key/value pair parameters are sent as a POST body. @format {string} Format data is returned in for processing, values are "json" or "text". Defaults to "json". Optional. @refreshInterval {int} Period of time for which the container can cache the data. If this parameter is set, it overrides the HTTP response header sent back from the makeRequest(). Optional. @authz. String, one of "none", "signed", "oauth", defaults to "none". This tells the gadget what authorization method to use when sending data to the remote server. @sign_viewer {boolean} Sign the request and include the current viewer id. Defaults to true. @sign_owner {boolean} Sign the request and include the current owner id. Defaults to true. @oauth_service_name {string} Identifies the service element in the gadget spec to use for this request. Default is "". @oauth_token_name {string} Identifies the OAuth token used to make a request to the service provider. Default is "". @oauth_request_token {string}. Identify a token that is pre-approved by the provider for access to the resource. @oauth_request_token_secret {string}. Secret associated with the pre-approved request token. @oauth_use_token {string}. Control whether an OAuth token should be used with the request. Allowed values are: "always" | "if_available" | "never"

Example: <os:HttpRequest key="Pets" href="http://example.com/api" authz="signed"/> os:HttpRequest produces a standard JSON-RPC object with "id", "error", and "result" properties. The "result" object is not available for 4xx or 5xx responses. When available, the "result" object in turn contains: content {object} If @format is "text", the string content of the response. If @format is "json", the parsed JSON object or array of the response. If a JSON response cannot be parsed, a 406 (Not Acceptable) error code will be produced. headers {object} An optional object with response header names as keys, and the header values as per-key arrays. status {int} The HTTP status code. For errors, the "message" property MUST NOT contain the response body, but SHOULD contain a descriptive message describing the HTTP error. The error MAY contain a data block providing the content and headers.

Examples: // @format='text' example {result: { content: 'Hi there!', status: 200, headers: {'Content-Type': ['text/plain;charset=utf-8']} }} // @format='json' example {result: { content: {'hi': 'there!'}, status: 200, headers: {'Content-Type': ['application/json;charset=utf-8']} }} // 404 error {error: { code: 404, message: 'Resource not found', // Optional data block data: { content : {'<html><body>File not found... '}, headers: {'Content-Type': ['text/html; charset=iso-8859-1']} } }} // Unparseable JSON {error: { message: "JSON could not be parsed", code: 406, data: { content: {'This isn't JSON'} } }}

Request to get profile information for a group or list of people. This is equivalent to using <os:DataRequest> with @method of "people.get". Attributes @key {string} @userId {list<string>} Comma delimited IDs of the users to use with "@groupId". Each item can be one of "@me", "@viewer", "@owner", or a user ID. @groupId {string} The group of users to get. Defaults to "@self", which returns the actual users listed in @userId. Other values are "@friends" to get friends, or any other string to get an arbitrary group. @fields {list<string>} Comma-delimited list of strings of OpenSocial profile fields to return. Optional. @startIndex {int}: Starting index to return results from. Optional. @count {int} Number of people to return. Optional. @sortBy {string} Specifies the field name whose value is be used to order the returned people. The sort order is determine by the sortOrder parameter. Optional. @sortOrder {string} The order in which the sortBy parameter is applied. Can either be "ascending" or "descending", defaults to ascending. Optional. @filterBy, @filterOp, @filterValue all {string} Filter to apply over users to retrieve, matches REST specification. Returns An array of OpenSocial person JSON objects.

Example: <os:PeopleRequest key="PagedFriends" userId="@owner" groupId="@friends" startIndex="40" count="20"/>

Requests to get the viewer's or owner's profile. This is equivalent to using <os:DataRequest> with @method of "people.get", with @userId of either "@viewer" or "@owner". Attributes @key {string} @fields {list<string>} Comma-delimited list of strings of OpenSocial profile fields to return. Optional. Returns An OpenSocial person JSON object.

Example: <os:ViewerRequest key="Viewer" fields="name, birthday"/>

Request to get activities. This is equivalent to using <os:DataRequest> with @method of "activities.get". Attributes @key {string} @userId {list<string>} Comma delimited IDs of the users to use with "@groupId". Each item can be one of "@me", "@viewer", "@owner", or a user ID. Required. @groupId {string} The group of users to get activities for. Defaults to "@self", which returns the actual users listed in @userid. Other values are "@friends" to get friends, or any other string to get an arbitrary group. Optional. @activityIds {list<string>} Comma delimited list of strings of activity ids to retreive. If set, @userid and @groupId will be ignored. Optional. @appId {String} ID of app to get information for. Defaults to current app, and containers are not required to support other values. Optional. @fields {list<string>} Comma-delimited list of strings of OpenSocial activity fields to return. Optional. @startIndex {int}: Starting index to return results from. Optional. @count {int} Number of activities to return. Optional. Returns An array of OpenSocial activity JSON objects.

Example: <os:ActivitiesRequest key="ViewerActivities" userid="@viewer" startIndex="40" count="20"/>

When embedding data pipelining a HTML content (either in CDATA or content returned with Content-Type:text/html from a proxied request), data pipelining tags are enclosed in a <script type="text/os-data"> block.

Example <Content type="html"><![CDATA[ <script xmlns:os="http://ns.opensocial.org/2008/markup" type="text/os-data"> <os:PeopleRequest key="vf" userId="@viewer" groupId="@friends"/> </script> <script type="text/os-template"> <div repeat="${vf}">${Name} is a friend.</div> </script> ]]> </Content> The first <script> block of type text/os-data must be processed by the data pipeline processor. Behavior is undefined with multiple script blocks. There is a general goal to be able to remove <script> blocks, but there are concerns in not having this <script> marker for processing, both in server and client-side implementations. We will experiment in the initial implementation and propose a streamlined syntax for the 1.0 OpenSocial release if possible.

Data pipelining tags can be top level elements in the <Content> section of a gadget using Proxied Content.

Example <Content href="http://example.com/canvas" xmlns:os="http://ns.opensocial.org/2008/markup"> <os:PeopleRequest key="vf" userId="@viewer" groupId="@friends"/> </Content> When preparing a request for proxied content, a container MUST process data pipelining elements that are direct children of the proxied content's <Content> element. Data pipelining elements are ALWAYS valid when preparing a request for proxied content, even if the opensocial-data feature is not present. The results of the data pipelining requests will be sent to the href of the <Content> section as POSTed JSON data. The structure will be in Batch JSON format. Elements in a data pipeline with @userId referencing the viewer (via @viewer, @me) will return a 403 (Forbidden) error response if the container is unable to also send the opensocial_viewer URL parameter to the 3rd party server. The same holds true for @owner and opensocial_owner URL parameter.

There will be new JavaScript APIs created to access the pipelined data on the client, all on the opensocial.data.DataContext object. There will be APIs to get the data returned from the data pipeline, set additional data, and listen to changes in data of a given key: opensocial.data.getContext() - Gets the DataContext associated with the gadget. opensocial.data.DataContext.getDataSet(string key) - Retrieves the object data that is currently mapped to the specified key. opensocial.data.DataContext.putDataSet(string key, json|object value) - Puts additional data into the data context keyed by the key. opensocial.data.DataContext.putDataSets(object dataSets) - Puts many data sets into the data context at once, with appropriate listeners firing after all the updates are done. dataSets is an object whose property names are data set keys, and whose properties are actual data sets. opensocial.data.DataContext.registerListener (array<String>|string keys, Function(array<String> keys) callback) - Listen for any updates to data keyed by one of "keys". You can also pass in the wildcard key "*" to listen to all keys. The callback function is invoked with an array of the keys that have changed as a parameter. Pipelined data is only available to the client when embedded in @type="html" content or content returned by a proxied content request. Data posted as part of a pipelined data request MUST not be available on the client.

Examples var viewer = opensocial.data.getContext().getDataSet('Viewer'); alert('Hello ' + viewer.name); os.data.getDataContext().putDataSet('Params', {"Page": 2, "PageSize": 10}); opensocial.data.getDataContext().registerListener('Friends', function(key) { var el = document.getElementById('friend-details'); el.style.display = 'show'; });

With pipelined data prepared for proxied content, errors are simply delivered to the href of the <Content> element as POSTed JSON data with the JSON-RPC error format unmodified. With pipelined data prepared for the Javascript API, or otherwise embedded in @type="html" content, per-item errors are not modified, but errors that fail the entire request are modified by cloning the error into each item.

Example <script xmlns:os="http://ns.opensocial.org/2008/markup" type="text/os-data"> <os:ViewerRequest key="vwr"/> <os:PeopleRequest key="vf" userId="@viewer" groupId="@friends"/> </script> If the above request failed with a server error, the resulting dataset would contain content resembling: {vwr: {error: {message: 'Server error', code: 500}}, vf: {error: {message: 'Server error', code: 500}}}

Containers should ignore unrecognized tags or return error code 404 (Not Found). If a tag is ignored, the JSON structure can either include a null value for the request key or just not include the request key.

The XML namespace for all of the Data Pipelining tags is http://ns.opensocial.org/2008/markup. (Note that namespace declarations on <Content> and <Module> elements do not apply to content inside of CDATA sections, so namespaces must be declared within CDATA.)

Data and HTTP requests often need to change based on input parameters. Two key use cases: Passing gadgets view parameters to a request, for example the current page in a paginated list. Passing OpenSocial data to a following <os:HttpRequest>, specifically IDs of (viewer, owner, viewer friends, owner friends). Data pipelining will support a limited subset of the expression language used in OpenSocial templates (based on JSP EL): Expressions of format ${A(.B)*} will be supported, where "A" is the key and "B" is any number of properties. Examples: ${UserPrefs.size}, ${ViewParams.nav.first}. Multiple expressions may appear within a single attribute, and mixed with non-expression text. The result of all non-expression text and expression evaluations will be concatenated. The key "ViewParams" is reserved and refers to the parameters passed into the gadget rendering, equivalent to gadgets.views.getParams(). The key "UserPrefs" is reserved and refers to gadget user preferences - ${UserPrefs.PREF} will return the value of gadgets.Prefs.getString('PREF') - see [API]. The results of expression evaluation are treated as if the results were inserted as the literal string value of the XML attribute. JSON arrays within ViewParams are output as "a,b", not "[a,b]". The results of expression evaluation for URL-typed attributes - specifically, @href and @param on <os:HttpRequest> - MUST be RFC 1738, Section 2.2 encoded (URL encoded) before being inserted into a final string. The following attributes support expressions: Any attribute on os:DataRequest other than @key and @method @userId @groupId @fields @startIndex @count @sortBy @sortOrder @filterBy @filterOp @filterValue @activityIds @href @params An implementation MUST evaluate dynamic properties for these attributes and MUST NOT evaluate dynamic properties for attributes not on this list.

Example <os:PeopleRequest key="PagedFriends" userId="@owner" groupId="@friends" startIndex="${ViewParams.first}" count="20"/> <os:HttpRequest href="http://example.com/api?ids=${PagedFriends.ids}"/>