Difference between revisions of "Gadgets.io (v0.9)"

From VZ Developer Wiki
Jump to: navigation, search
Line 60: Line 60:
 
changes URLs.</li>
 
changes URLs.</li>
 
     <li>'''opensocial_instance_id''' - An opaque identifier used to distinguish between multiple instances of the same application in a single container. If a container does not allow multiple instances of the same application to coexist, this parameter may be omitted. The combination of opensocial_app_url and opensocial_instance_id uniquely identify an instance of an application in a container.</li>
 
     <li>'''opensocial_instance_id''' - An opaque identifier used to distinguish between multiple instances of the same application in a single container. If a container does not allow multiple instances of the same application to coexist, this parameter may be omitted. The combination of opensocial_app_url and opensocial_instance_id uniquely identify an instance of an application in a container.</li>
     <li>'''opensocial_app_id''' - An opaque identifier for the application, unique to a particular container. Containers that wish to maintain backwards compatibility with the opensocial-0.7 specification may include this parameter.</li>
+
     <li>'''opensocial_app_id''' - The gadget id.</li>
 
     <li>'''xoauth_public_key''' - An opaque identifier for the public key used to sign the request. This parameter may be omitted by containers that do not use public keys to sign requests, or if the container arranges other means of key distribution with the target of the request.</li>
 
     <li>'''xoauth_public_key''' - An opaque identifier for the public key used to sign the request. This parameter may be omitted by containers that do not use public keys to sign requests, or if the container arranges other means of key distribution with the target of the request.</li>
 
   </ul>
 
   </ul>

Revision as of 11:38, 30 July 2010

gadgets.io

Provides remote content retrieval functions.

Methods

gadgets.io.encodeValues

<static> String gadgets.io.encodeValues(fields)
Parameters
Name Type Description
fields Object The post fields you wish to encode
Returns
Type Description
String The processed post data; this includes a trailing ampersand (&)
Description
Converts an input object into a URL-encoded data string. (key=value&...)

gadgets.io.getProxyUrl

<static> String gadgets.io.getProxyUrl(url, opt_params)
Parameters
Name Type Description
url String The URL to get the proxy URL for
opt_params Map<String|String> Optional proxy request parameters to pass to the request
Returns
Type Description
String The proxied version of the URL
Description
Gets the proxy version of the passed-in URL.

gadgets.io.makeRequest

<static> gadgets.io.makeRequest(url, callback, opt_params)
Parameters
Name Type Description
url String The URL where the content is located
callback Function The function to call with the data from the URL once it is fetched. The callback function will not be called until after the existing callstack has completed execution.
opt_params Map.<gadgets.io.RequestParameters|Object> Additional request parameters
Description
Fetches content from the provided URL and feeds that content into the callback function. Note that the hosts or IPs you are requesting have to be whitelisted in your Gadget XML, see Gadgets_XML#ModulePrefs.2FAllowedDomain.
var params = {}; 
params[gadgets.io.RequestParameters.CONTENT_TYPE] = gadgets.io.ContentType.TEXT; 
gadgets.io.makeRequest(url, callback, params);
Signed authorization
If opt_params[gadgets.io.RequestParameters.AUTHORIZATION] is set to

gadgets.io.AuthorizationType.SIGNED, the container needs to vouch for the user's identity to the destination server. The container does this by doing the following:

  1. Removing any request parameters with names that begin with oauth, xoauth, or opensocial (case insensitive).
  2. Adding the following parameters to the request query string:
    • opensocial_viewer_id - The ID of the current viewer, which matches the getId() value on the viewer person object.
    • opensocial_owner_id - The ID of the current owner, which matches the getId() value on the owner person object.
    • opensocial_app_url - The URL of the application making the request. Containers may alias multiple application URLs to a single canonical application URL in the case where an application changes URLs.
    • opensocial_instance_id - An opaque identifier used to distinguish between multiple instances of the same application in a single container. If a container does not allow multiple instances of the same application to coexist, this parameter may be omitted. The combination of opensocial_app_url and opensocial_instance_id uniquely identify an instance of an application in a container.
    • opensocial_app_id - The gadget id.
    • xoauth_public_key - An opaque identifier for the public key used to sign the request. This parameter may be omitted by containers that do not use public keys to sign requests, or if the container arranges other means of key distribution with the target of the request.
  3. Signing the resulting request according to section 9 of the OAuth specification.
management for gadgets.io.AuthorizationType.SIGNED

If a container uses public keys to sign requests, the container may choose to use either self-signed certificates or certificates signed by a well-known certificate authority. If a container does not distribute its OAuth signing key over HTTPS, it should use a certificate signed by a well-known certificate authority.

The commonName attribute of the certificate should match the hostname of the container server, and should also match the value of the oauth_consumer_key parameter specified in the request.

The container should make its public key available for download at a well-known location. The location https://[container-hostname]/opensocial/certificates/xoauth_public_keyvalue is recommended.

Recipients of signed requests must verify that the signature on the request is correct, and that the timestamp on the request is within a reasonable time window. A time window of 5 minutes before and after the current time is recommended.

Recipients of signed requests may use the oauth_consumer_key and xoauth_public_key parameters to automatically detect when a container deploys new certificates. If the container deploys certificates at a well-known location, the recipient may automatically download the new certificate. Recipients that automatically download new certificates should cache the resulting certificates.

If a container's certificate is not downloaded from https://[container-hostname], the recipient should verify that the certificate is signed by a well-known certificate authority before trusting the certificate.

OAuth authorization

If opt_params[gadgets.io.RequestParameters.AUTHORIZATION] is set to gadgets.io.AuthorizationType.OAUTH, the container needs to use OAuth to gain access to the resource specified in the request. This may require that the gadget obtain the user's content by directing the user to the service provider to gain access.

Additional parameters

The following additional parameters may be specified in opt_params:

  • gadgets.io.RequestParameters.OAUTH_SERVICE_NAME - The nickname the gadget uses to refer to the OAuth <Service> element from its XML spec. If unspecified, defaults to "".
  • gadgets.io.RequestParameters.OAUTH_TOKEN_NAME - The nickname the gadget uses to refer to an OAuth token granting access to a particular resources. If unspecified, defaults to "". Gadgets can use multiple token names if they have access to multiple resources from the same service provider. For example, a gadget with access to a contact list and a calendar might use a token name of "contacts" to use the contact list token, and a contact list of "calendar" to use the calendar token.
  • gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN - A service provider may be able to automatically provision a gadget with a request token that is preapproved for access to a resource. The gadget can use that token with the OAUTH_REQUEST_TOKEN parameter. This parameter is optional.
  • gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN_SECRET - The secret corresponding to a preapproved request token. This parameter is optional.

If OAuth is used, the container should execute the OAuth protocol on behalf of the gadget. If the gadget has not registered a consumer key for use with this service provider, the container may choose to use a default RSA signing key corresponding to a well-known certificate to sign requests. If the container uses a default consumer key, it will include an additional OAuth parameter xoauth_app_url that identifies the gadget making the request.

The callback parameter

The makeRequest() callback parameter is passed a javascript object with the following standard fields:

  • "data" - Parsed data of the response, if applicable. This will contain a different type of data depending on the type of request that was made. See the ContentType parameters for information about what to expect in this field. The raw response text is returned if the response could not be parsed.
  • "errors" - This will contain an array of any errors that occurred when making this request. For example, if a 500 error occurred in the request: [ "500 error" ]
  • "headers" - An object containing the response headers. Header names are used as the keys for this object.
  • "rc" - This is a numeric value representing the HTTP status code of the response.
  • "text" - This will return the unparsed text of the response.

Additionally, several OAuth-specific fields may be returned:

  • "oauthApprovalUrl" - If this value is specified, the user needs to visit an external page to approve the gadget's request to access data. Use of a pop-up window to direct the user to the external page is recommended. Once the user has approved access, the gadget can repeat the makeRequest call to retrieve the data.
  • "oauthError" - If this value is specified, it indicates an OAuth-related error occurred. The value will be one of a set of string constants that can be used for programmatically detecting errors. The constants are undefined for opensocial-0.8, but implementers should attempt to agree on a set of useful constant values for standardization in opensocial-0.9.
  • "oauthErrorText" - If this value is specified, it indicates an OAuth-related error occurred. The value is free-form text that can be used to provide debugging information for gadget developers.

gadgets.io.AuthorizationType

Used by RequestParameters.

gadgets.io.AuthorizationType.NONE

No authorization. This field may be used interchangeably with the string 'NONE'.

gadgets.io.AuthorizationType.OAUTH

The container will use OAuth for authentication. This field may be used interchangeably with the string 'OAUTH'.

gadgets.io.AuthorizationType.SIGNED

The request will be signed by the container. This field may be used interchangeably with the string 'SIGNED'.

gadgets.io.ContentType

Used by RequestParameters.

gadgets.io.ContentType.DOM

Returns a DOM object; used for fetching XML. This field may be used interchangeably with the string 'DOM'. DOM requests attempt to retrieve a remote web page and parse it into a DOM document. You can use standard DOM manipulation/query methods on the resulting document to work with nodes in the response.

Make a DOM request like this:

 
function request() {  
  var params = {};
  params[gadgets.io.RequestParameters.CONTENT_TYPE] = gadgets.io.ContentType.DOM;
  var url = "http://example.com";
  gadgets.io.makeRequest(url, response, params);
};

If the request is successful, the response will come back with the raw XML in the text field and the DOM object in the data field.

function response(obj) {
  /** obj.data contains a DOM element corresponding to the requested page **/
};

If the content at http://example.com is the following document:

<?xml version="1.0"?>
<root>
  <title>Hello!</title>
</root>

The obj.text property will have the following value:

 
"<?xml version=\"1.0\"?>\n<root>\n  <title>Hello!</title>\n</root>"

The obj.data property will have the following general structure (many of the attributes available on the returned XML document have been left out for clarity).

{
  ...
 
  nodeName : "#document",
  childNodes : [
    {
      nodeName : "root",
      childNodes : [
        "\n",
        {
          nodeName : "title",
          childNodes : [ "Hello!" ]
        },
        "\n"
      ]
    }
  ],
 
  ...
}

gadgets.io.ContentType.FEED

Returns a JSON representation of an RSS or Atom feed. This field may be used interchangeably with the string 'FEED'. Feed requests attempt to parse an ATOM or RSS xml feed and return the response as a JSON encoded object.

Specify a feed content type like this:

function request() {  
  var params = {};
  params[gadgets.io.RequestParameters.CONTENT_TYPE] = gadgets.io.ContentType.FEED;
  var url = "http://example.com";
  gadgets.io.makeRequest(url, response, params);
};

If the request is successful, then the response will come back with the raw XML text in the text field and the parsed JavaScript object in the data field:

 
function response(obj) {
  /** obj.data contains an object corresponding with the JSON-encoded response **/
};

If the content at http://example.com is the following:

 
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Example Feed</title>
  <subtitle>A subtitle.</subtitle>
  <link href="http://example.com/feed/" rel="self"/>
  <link href="http://example.com/"/>
  <updated>2008-03-12T18:30:02Z</updated>
  <author>
    <name>Sample Testington</name>
    <email>stestington@example.com</email>
  </author>
  <id>urn:uuid:60a76c80-d399-11d9-b91C-0003939e0af6</id>
  <entry>
    <title>You can request feeds with makeRequest</title>
    <link href="http://example.com/entry12345"/>
    <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
    <updated>2008-03-12T18:30:02Z</updated>
    <summary>Some text.</summary>
  </entry>
</feed>

The obj.text property will be set to the text of the xml document. The obj.data property will have the following structure:

{
  URL : "http://example.com",
  Title : "Example Feed",
  Description : "A subtitle.",
  Link : "http://example.com/feed/",
  Author : "Sample Testington",
  Entry : [
    {
      Title : "You can request feeds with makeRequest",
      Link : "http://example.com/entry12345",
      Summary : "Some text."
    }
  ]
}

gadgets.io.ContentType.JSON

Returns a JSON object. This field may be used interchangeably with the string 'JSON'. JSON requests attempt to parse the response as a JSON encoded object.

Specify a JSON content type like this:

function request() {  
  var params = {};
  params[gadgets.io.RequestParameters.CONTENT_TYPE] = gadgets.io.ContentType.JSON;
  var url = "http://example.com";
  gadgets.io.makeRequest(url, response, params);
};

If the request is successful, then the response will come back with the raw JSON string in the text field and the parsed JavaScript object in the data field:

function response(obj) {
  /** obj.data contains an object corresponding with the JSON-encoded response **/
};

If the content at http://example.com is the following:

{ "Message" : "Hello!", "Test" : [ "Item 1", "Item 2" ] }

The obj.text property will have the following value:

 
"{ \"Message\" : \"Hello!\", \"Test\" : [ \"Item 1\", \"Item 2\" ] }"

The obj.data property will have the following structure:

{
  Message : "Hello!",
  Test : [
    "Item 1",
    "Item 2"
  ]
}

gadgets.io.ContentType.TEXT

Returns text; used for fetching HTML. This field may be used interchangeably with the string 'TEXT'. Text requests are the default content type for makeRequest calls. Text content type requests do not make any attempt to parse the content of the response.

Make a text content request like this:

 function request() {  
   var params = {};
   params[gadgets.io.RequestParameters.CONTENT_TYPE] = gadgets.io.ContentType.TEXT;
   var url = "http://example.com";
   gadgets.io.makeRequest(url, response, params);
 };

If the request is successful, the response will come back with both the text and data fields populated with the raw response text.

function response(obj) {
  /** obj.text contains the text of the page that was requested **/
};

If the content at http://example.com is the following:

<html>
  <body>
    <h1>Hello!</h1>
  </body>
</html>

Then obj.text and obj.data fields will have the following value:

"<html>\n  <body>\n    <h1>Hello!</h1>\n  </body>\n</html>"

gadgets.io.MethodType

Defines values for RequestParameters.METHOD.

gadgets.io.MethodType.DELETE

Container support for this method type is OPTIONAL. This field may be used interchangeably with the string 'DELETE'.

gadgets.io.MethodType.GET

The default type. This field may be used interchangeably with the string 'GET'. Typically, you use GET to retrieve information from a website. GET is the default mode for makeRequest, but you can explicitly make a GET request with the following code:

function makeRequest(url) {
  var params = {};
  params[gadgets.io.RequestParameters.METHOD] = gadgets.io.MethodType.GET;
  gadgets.io.makeRequest(url, response, params);
};
 
function response(obj) {
  alert(obj.text);
};
 
makeRequest("http://example.com");

To pass parameters to your server in the GET request, just append them to the querystring when you make the request:

makeRequest("http://example.com?param1=12345&param2=hello");

gadgets.io.MethodType.HEAD

Container support for this method type is OPTIONAL. This field may be used interchangeably with the string 'HEAD'.

gadgets.io.MethodType.POST

Container support for this method type is OPTIONAL. This field may be used interchangeably with the string 'POST'. POST requests are typically used to pass data to a server with the intent to modify or delete records. You can pass larger amounts of data in a POST request than you would be normally able to with a GET request.

Perform a POST by using the following code:

function makeRequest(url, postdata) {
  var params = {};
  postdata = gadgets.io.encodeValues(postdata);
  params[gadgets.io.RequestParameters.METHOD] = gadgets.io.MethodType.POST;
  params[gadgets.io.RequestParameters.POST_DATA]= postdata;
  gadgets.io.makeRequest(url, response, params);
};
 
function response(obj) {
  output(obj.text);
};
 
var data = {
  data1 : "test",
  data2 : 123456
};
 
makeRequest("http://example.com", data);

In addition to specifying the METHOD in the opt_params for this request, you should specify a parameter under the key gadgets.io.RequestParameters.POST_DATA. The default encoding for POST is application/x-www-form-urlencoded which means that the value for the POST_DATA parameter should be a series of urlencoded key/value pairs joined with ampersands (&). To make converting objects of data into this format easier, the function gadgets.io.encodeValues is provided. encodeValues accepts a JavaScript object and returns an encoded string suitable for the POST_DATA parameter.

For example, running:

 
var data = {
  data1 : "test",
  data2 : 123456
};

gadgets.io.encodeValues(data);

produces the string:

"data1=test&data2=123456"

This string can be passed directly as the value for gadgets.io.RequestParameters.POST_DATA.

gadgets.io.MethodType.PUT

Container support for this method type is OPTIONAL. This field may be used interchangeably with the string 'PUT'.

gadgets.io.ProxyUrlRequestParameters

Used by gadgets.io.getProxyUrl() method.

gadgets.io.ProxyUrlRequestParameters.REFRESH_INTERVAL

<static> Member of: gadgets.io.ProxyUrlRequestParameters.REFRESH_INTERVAL Explicitly sets the lifespan of cached content. The Refresh Interval is the number of seconds the container should cache the given response. By default, the HTTP caching headers will be respected for fetched content. If the refresh interval is set, this value will take precedence over any HTTP cache headers. If this value is not set and there are no HTTP caching headers specified, this value will default to 3600 (one hour). Note that Signed requests and objects with POST_DATA present will generally not be cached. This field may be used interchangeably with the string 'REFRESH_INTERVAL'.

gadgets.io.RequestParameters

Used by the gadgets.io.makeRequest() method.

gadgets.io.RequestParameters.AUTHORIZATION

<static> Member of: gadgets.io.RequestParameters.AUTHORIZATION The type of authentication to use when fetching the content; defaults to AuthorizationType.NONE. Specified as an AuthorizationType. This field may be used interchangeably with the string 'AUTHORIZATION'.

gadgets.io.RequestParameters.CONTENT_TYPE

<static> Member of: gadgets.io.RequestParameters.CONTENT_TYPE The type of content that lives at the URL; defaults to ContentType.TEXT. Specified as a ContentType. This field may be used interchangeably with the string 'CONTENT_TYPE'.

gadgets.io.RequestParameters.GET_SUMMARIES

<static> Member of: gadgets.io.RequestParameters.GET_SUMMARIES If the content is a feed, whether to fetch summaries for that feed; defaults to false. Specified as a Boolean. This field may be used interchangeably with the string 'GET_SUMMARIES'.

gadgets.io.RequestParameters.HEADERS

The HTTP headers to send to the URL; defaults to null. Specified as a Map.<String,String>. This field may be used interchangeably with the string 'HEADERS'.

var params = {}; 
params[gadgets.io.RequestParameters.HEADERS] = {
  "Content-Type" : "application/atom+xml",
  "Accept-Language": "en-us"
}
gadgets.io.makeRequest(url, callback, params);

gadgets.io.RequestParameters.METHOD

The method to use when fetching content from the URL; defaults to MethodType.GET. Valid values are specified by MethodType. This field may be used interchangeably with the string 'METHOD'.

gadgets.io.RequestParameters.NUM_ENTRIES

If the content is a feed, the number of entries to fetch; defaults to 3. Specified as a Number. This field may be used interchangeably with the string 'NUM_ENTRIES'.

gadgets.io.RequestParameters.POST_DATA

The data to send to the URL using the POST method; defaults to null. Specified as a String. This field may be used interchangeably with the string 'POST_DATA'.

var params = {}; 
params[gadgets.io.RequestParameters.POST_DATA] = gadgets.io.encodeValues({
  data1 : "test",
  data2 : 123456
});
gadgets.io.makeRequest(url, callback, params);

gadgets.io.RequestParameters.REFRESH_INTERVAL

<static> Member of: gadgets.io.RequestParameters.REFRESH_INTERVAL Explicitly sets the lifespan of cached content. The Refresh Interval is the number of seconds the container should cache the given response. By default, the HTTP caching headers will be respected for fetched content. If the refresh interval is set, this value will take precedence over any HTTP cache headers. If this value is not set and there are no HTTP caching headers specified, this value will default to 3600 (one hour). Note that Signed requests and objects with POST_DATA present will generally not be cached. This field may be used interchangeably with the string 'REFRESH_INTERVAL'.



OpenSocial (v0.9)

gadgets

gadgets.io

gadgets.json

gadgets.Prefs

gadgets.util

gadgets.views

gadgets.flash

gadgets.MiniMessage

gadgets.oauth.Popup

gadgets.rpc

gadgets.skins

gadgets.pubsub

gadgets.Tab

gadgets.TabSet

gadgets.window

gadgets.i18n

opensocial

opensocial.Activity

opensocial.Address

opensocial.Album

opensocial.BodyType

opensocial.Collection

opensocial.CreateActivityPriority

opensocial.DataRequest

opensocial.DataResponse

opensocial.Email

opensocial.Enum

opensocial.Environment

opensocial.EscapeType

opensocial.IdSpec

opensocial.MediaItem

opensocial.Message

opensocial.MessageCollection

opensocial.Name

opensocial.NavigationParameters

opensocial.Organization

opensocial.Permission

opensocial.Person

opensocial.Phone

opensocial.ResponseItem

opensocial.Url

osapi.Request

osapi.BatchRequest

osapi.people

osapi.activities

osapi.appdata

osapi.messages

osapi.http