| OpenSocial | OpenSocial and Gadgets Specification Group |
| <opensocial-data-pipelining-specification-v0_9> | April 15, 2009 |
OpenSocial Data Pipelining Specification v0.9
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 [RFC2119]. Domain name examples use RFC2606 [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:
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:
<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:
<ModulePrefs> <Require feature="opensocial-data"/> </ModulePrefs>
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
Returns
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 [GadgetsSpec]. Containers will typically cache the results of these requests; see the Gadget section 4.2 [GadgetsSpec] and OpenSocial section 4.2.6 [osspec] specifications for more information.
Attributes
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:
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
Returns
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
Returns
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
Returns
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 [GadgetsSpec].
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 [RPCProtocol] 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:
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:
Data pipelining will support a limited subset of the expression language used in OpenSocial templates (based on JSP EL [JSPEL]):
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:
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}"/>
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels" , RFC 2119, March 1997. |
| [RFC2606] | Eastlake, D. and A. Panitz, "Reserved Top Level DNS Names" , RFC 2606, June 1999. |
| [GadgetsSpec] | social, o., "Gadgets API Specification 0.9" , January 2009, <Gadgets-API-Specification.html>. |
| [RPCProtocol] | social, o., "OpenSocial RPC Protocol Specification v0.9" , January 2009, <RPC-Protocol.html>. |
| [JSPEL] | Chung, K., DeLisle, P., and M. Roth, "Java Server Pages Expression Language" , May 2006, <https://jsp.dev.java.net/spec/jsp-2_1-fr-spec-el.pdf>. |
| [osspec] | social, o., "OpenSocial Specification v0.9" , January 2009, <Opensocial-Specification.html>. |