Author: scottbw
Date: Fri Mar 23 11:26:08 2012
New Revision: 1304283
URL: http://svn.apache.org/viewvc?rev=1304283&view=rev
Log:
Added 0.9.x API reference page
Added:
incubator/wookie/site/trunk/content/wookie/docs/api_9.mdtext (with props)
Added: incubator/wookie/site/trunk/content/wookie/docs/api_9.mdtext
URL:
http://svn.apache.org/viewvc/incubator/wookie/site/trunk/content/wookie/docs/api_9.mdtext?rev=1304283&view=auto
==============================================================================
--- incubator/wookie/site/trunk/content/wookie/docs/api_9.mdtext (added)
+++ incubator/wookie/site/trunk/content/wookie/docs/api_9.mdtext Fri Mar 23
11:26:08 2012
@@ -0,0 +1,427 @@
+Title: Wookie API Reference (version 0.9.x)
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+This is the API reference for Wookie 0.9.0 to 0.9.2. For later versions of
Wookie, see the [current API docs][1]
+
+# API key
+
+Note that except where noted, all methods require the requesting application
to have a valid API key issued by the Wookie server administrator.
+
+
+# Widget Instances (from 0.9.0)
+An instance is identified using a combination of the following parameters:
+
+- api_key: The key issued to a particular application
+- shareddatakey: The key generated by an application representing a specific
context (e.g. a page, post, section, group or other identified context)
+- userid: An identifier (typically a hash rather than a real user Id) issued
by an application representing the current viewer of the widget instance
+- widgetid: The URI of the widget this is an instance of (optional, see
servicetype below)
+- servicetype: Where an individual widget is not requested by URI as above,
this parameter should contain the category of widget to be instantiated, e.g.
"chat"
+- locale: The preferred locale of the widget, expressed using a BCP47 Language
Tag
+
+##Representation
+
+An instance is represented in XML as follows:
+
+ <widgetdata>
+ <url>URL TO ACCESS WIDGET</url>
+ <identifier>IH6rjs75tkb6I.pl.k0hUq7YdnFcjw.eq.</identifier>
+ <title>Weather</title>
+ <height>125</height>
+ <width>125</width>
+ </widgetdata>
+
+<table border="1">
+<tr>
+ <th>Request</th>
+ <th>Description</th>
+</tr>
+
+<tr>
+ <td>GET {wookie}/widgetinstances</td>
+ <td>Not supported.</td>
+</tr>
+
+<tr>
+ <td>GET {wookie}/widgetinstances/{instance id_key}</td>
+ <td>Returns the representation of a widget instance. If the widget instance
was not created using the provided api_key, then a 403 Forbidden status code
will be returned. If no widget instance is found, a 404 Not Found status code
will be returned. .</td>
+</tr>
+
+<tr>
+ <td>GET {wookie}/widgetinstances/ {params:instance_params}</td>
+ <td>Returns the representation of a widget instance. If the widget instance
was not created using the provided api_key, then a 403 Forbidden status code
will be returned. If no widget instance is found, a 404 Not Found status code
will be returned. .</td>
+</tr>
+
+<tr>
+ <td>POST {wookie}/widgetinstances {params:instance_params}</td>
+<td>
+Create a new widget instance using the given parameters. If a new widget
instance is succesfully created, a status code of 201 is returned along with
the widget instance represented in XML.
+
+If an instance already exists for the given parameters, this method will
return a status code of 200 along with the existing instance (this is intended
to support legacy clients).
+</td>
+</tr>
+
+<tr>
+ <td>PUT {wookie}/widgetinstances {params:instance_params, action,
[cloneshareddatakey]}</td>
+ <td>Either stop, resume, or clone an instance, depending on the content of
the action parameter. If the action is "clone", a shared data key for the clone
must be provided using the "cloneshareddatakey" parameter.</td>
+</tr>
+</table>
+
+# Widgets (from 0.9.0)
+
+##Representation
+
+A Widget is currently represented in XML using an abbreviated form of the W3C
Widgets packaging format:
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <widgets>
+ <widget id="7" identifier="http://wookie.apache.org/widgets/geo";
width="620" height="660" version="0.1">
+ <title short="">geo</title>
+ <description>An example of a HTML 5 geolocation
widget.</description>
+
<icon>http://localhost:8080/wookie/wservices/wookie.apache.org/widgets/geo/icon.svg</icon>
+ <author>Apache Wookie (Incubating) Team</author>
+ </widget>
+ </widgets>
+
+**Note** the "id" attribute is a Wookie-specific identifier that should be
used as the URL parameter for REST API methods; in the above example, requests
relating to this widget would
+be addressed to /widgets/7. The "identifier" attribute corresponds to the W3C
WIdgets "identifier" attribute, and contains the URI of the Widget,
+
+<table border="1"><tbody>
+<tr>
+<th >Request</th>
+<th >Description</th>
+</tr>
+<tr>
+<td > GET {wookie}/widgets{?all=true, locale=<em>language_tag</em>} </td>
+<td > Returns an XML representation of the set of available widgets. Note that
this does not require an API key.
+ If a locale is specified, the returned information is localized, for example
widget titles, descriptions, license information will be in the specified
language where available.
+
+(Note: For versions before 0.10.0, if the "all=true" parameter is omitted, the
list only contains the default widgets for defined service types. This
parameter is ignored from 0.10.0 onwards)
+</td>
+</tr>
+<tr>
+<td > GET {wookie}/widgets/{service_name} {?locale=<em>language_tag</em>} </td>
+<td > Returns an XML representation of the set of widgets matching the service
(category) specified. (Deprecated: Removed from 0.10 onwards) </td>
+</tr>
+<tr>
+<td > GET {wookie}/widgets/{id} {?locale=<em>language_tag</em>}</td>
+<td > Returns an XML representation of the widget with the specified
<em>id</em>. Note that in the current release this is the actual database key;
future releases should implement this using the widget URI as the <em>id</em>.
If a locale is specified, the returned information is localized, for example
widget titles, descriptions, license information will be in the specified
language where available.</td>
+</tr>
+<tr>
+<TD> POST {wookie}/widgets {file} </TD>
+<TD> Posts a widget file to the server; this is identical in behaviour to
dropping a ".wgt" file into the Wookie deploy folder. This method
requires authentication using a widgetadmin role, e.g. using HTTP Basic
authentication</TD>
+</tr>
+</tbody></table>
+
+#Participants (from 0.9.0)
+
+A Participant consists of a <em>participant_display_name</em>,
<em>participant_id</em>, and <em>participant_thumbnail_url</em>. Participants
are always defined in relation to a specific Widget Instance; requests
affecting one Participant have no effect on Participants associated with other
Widget Instances.
+
+##Representation
+
+Participants are represented in XML as a <participants> document,
containing a <participant> element for each participant, with the
attributes:
+
+- id: the participant id (not to be confused with Wookie's internal id of a
participant)</li>
+- display_name: the participant display name</li>
+- thumbnail_url: the url of the thumbnail image for the participant</li>
+
+
+<table border="1"><tbody>
+<tr>
+<th >Request</th>
+<th >Description</th>
+</tr>
+<tr>
+<td >GET {wookie}/participants </td>
+<td > Not supported.</td>
+</tr>
+<tr>
+<td >GET {wookie}/participants {params: <em>instance_params</em>}</td>
+<td > Returns an XML representation of the Participants associated with the
Widget instance specified by {instance params}.</td>
+</tr>
+<tr>
+<td >GET {wookie}/participants {params:id_key, api_key}</td>
+<td >Returns an XML representation of the Participants associated with the
Widget instance specified by {id_key}.</td>
+</tr>
+<tr>
+<td >POST {wookie}participants {params: <em>instance_params</em>,
participant_id, participant_display_name, participant_thumbnail_url}</td>
+<td >Adds a participant to the specified Widget Instance. If successful, a
HTTP status code of 201 is returned. If there is already a participant that
matches {participant params} for the instance, a HTTP status code of 200 is
returned.</td>
+</tr>
+<tr>
+<td >DELETE {wookie}/participants {params: <em>instance_params</em>,
participant_id}</td>
+<td >Deletes the specified Participant from the specified Widget Instance.</td>
+</tr>
+</tbody></table>
+
+
+#Properties (from 0.9.0)
+
+The Properties API contains methods for both Preferences (properties affecting
a single Widget Instance) and Shared Data (properties affecting sibling
Widgets).
+
+A property consists of a <em>propertyname</em> and <em>propertyvalue</em>.
+
+<table border="1"><tbody>
+<tr>
+<th >Request</th>
+<th >Description</th>
+</tr>
+<tr>
+<td >GET {wookie}/properties</td>
+<td >Not supported.</td>
+</tr>
+<tr>
+<td >GET {wookie}/properties {params: <em>instance_params</em>,
propertyname}</td>
+<td >Returns the value of the specified property for the specified
instance.</td>
+</tr>
+<tr>
+<td >POST {wookie}/properties {params: <em>instance_params</em>, propertyname,
propertyvalue, [is_public=true]}</td>
+<td >Sets a property for the specified instance. If is_public=true is set, the
property set is a Shared Data entry; otherwise it is a Preference.</td>
+</tr>
+<tr>
+<td >PUT {wookie}/properties {params: <em>instance_params</em>,
propertyname, propertyvalue}</td>
+<td >Updates the value of the specified property of the specified Widget
Instance.</td>
+</tr>
+<tr>
+<td >DELETE {wookie}/properties {params: <em>instance_params</em>,
propertyname}</td>
+<td >Deletes a property. This method returns a 404 status code if there is no
matching property. </td>
+</tr>
+</tbody></table>
+
+
+#Flatpack (from 0.9.1)
+
+The Flatpack API contains methods for exporting a Widget Instance as a new
Widget package (.wgt file) that can be downloaded by a client.
+
+This can be used, for example, for a plugin to support users exporting the
widget (including any preferences they have set) for side-loading onto a mobile
device or running in a desktop environment like Opera Widgets.
+
+**Note** this is new functionality only available in latest builds, and has a
number of limitations (for example, Widgets using features like Wave won't
export properly).
+<table border="1"><tbody>
+<tr>
+<th >Request</th>
+<th >Description</th>
+</tr>
+<tr>
+<td >GET {wookie}/flatpack</td>
+<td >Not supported.</td>
+</tr>
+<tr>
+<td >GET {wookie}/flatpack/{package_id}.wgt</td>
+<td >Downloads the specified widget package.</td>
+</tr>
+<tr>
+<td >POST {wookie}/flatpack {params: <em>instance_params</em></td>
+<td >creates a new W3C Widget package (.wgt) with an opaque file name for the
specified widget instance, and returns the download URL. </td>
+</tr>
+</tbody></table>
+
+#Administration Functions
+
+The following sections describe the API invoked by admin clients for managing
the Wookie server, e.g. for managing whitelist entries or widget access
policies.
+
+##Authentication
+By default the Admin REST API is secured using the Admin security restrictions
defined in web.xml. This means that typically the client needs to have
authenticated with the server using the admin user credentials.
+
+##Response formats
+Clients may request a response in either XML or JSON by setting the
appropriate request content type. (If it is not possible to specify a content
type in the request, clients may use the optional "format" parameter to specify
a content type override.)
+
+## API Keys (from 0.9.1)
+
+This API is used to manage API Keys for applications accessing Wookie.
+
+<TABLE border="1"><TBODY>
+<TR>
+<TH>Request</TH>
+<TH>Description</TH>
+</TR>
+<TR>
+
+<TD> GET {wookie}/keys </TD>
+
+<TD> Returns all API keys. This method requires authentication using a
widgetadmin role, e.g. using HTTP Basic authentication</TD>
+</TR>
+<TR>
+
+<TD> POST {wookie}/keys/ {param:apikey, email} </TD>
+
+<TD> Creates a new API key with the details provided. This method requires
authentication using a widgetadmin role, e.g. using HTTP Basic
authentication.</TD>
+</TR>
+<TR>
+
+<TD> PUT {wookie}/keys/{id} {param: apikey, email} </TD>
+
+<TD>**NOT YET IMPLEMENTED**. Updates the API Key specified by <EM>id</EM>.
This method requires authentication using a widgetadmin role, e.g. using HTTP
Basic authentication.</TD>
+</TR>
+<TR>
+
+<TD> DELETE {wookie}/keys/{id} </TD>
+
+<TD> Deletes the API key specified by <EM>id</EM>. This method requires
authentication using a widgetadmin role, e.g. using HTTP Basic
authentication.</TD>
+</TR>
+</TBODY></TABLE>
+
+
+## Policies (from 0.9.2)
+
+This API is used to manage access policies for the server-side proxy. Note
that policy strings should conform to the *scope origin directive* format as
described in the `policies` file.
+
+*This API replaces the WARP and Whitelist APIs defined in 0.9.1.*
+
+<TABLE border="1"><TBODY>
+<TR>
+<TH>Request</TH>
+<TH>Description</TH>
+</TR>
+<TR>
+
+<TD> GET {wookie}/policies </TD>
+
+<TD> Returns all policies. This method requires authentication using a
widgetadmin role, e.g. using HTTP Basic authentication</TD>
+</TR>
+<TR>
+
+<TD> GET {wookie}/policies/{scope} </TD>
+
+<TD> Returns policies matching the specified scope (e.g. a URL-encoded Widget
URI). This method requires authentication using a widgetadmin role, e.g. using
HTTP Basic authentication</TD>
+</TR>
+<TR>
+
+<TD> POST {wookie}/policies/</TD>
+
+<TD> Creates a new policy using a policy string supplied in the body of the
POST message. This method requires authentication using a widgetadmin role,
e.g. using HTTP Basic authentication.</TD>
+</TR>
+<TR>
+
+<TD> DELETE {wookie}/policies/{policy} </TD>
+
+<TD> Deletes the policy specified by <EM>policy</EM> which should be a
URL-encoded policy string. This method requires authentication using a
widgetadmin role, e.g. using HTTP Basic authentication.</TD>
+</TR>
+</TBODY></TABLE>
+
+
+# Deprecated and Legacy APIs
+
+
+##Widget Access Request Policies (WARP) (0.9.1 only)
+
+This API is used to manage per-Widget access request policies in accordance
with the [W3C Widgets Access Request Policy][2] specification.
+
+*This API was replaced by the unified Policies API in 0.9.2*
+
+<TABLE border="1"><TBODY>
+<TR>
+<TH>Request</TH>
+<TH>Description</TH>
+</TR>
+<TR>
+
+<TD> GET {wookie}/warp {param: widgetId} </TD>
+
+<TD> Returns all access policies, or only the access policies that apply to
the widget identified by the <EM>widgetId</EM> parameter. This method requires
authentication using a widgetadmin role, e.g. using HTTP Basic
authentication</TD>
+</TR>
+<TR>
+
+<TD> GET {wookie}/warp/{id} </TD>
+
+<TD> Returns the access policy specified by <EM>id</EM>. This method requires
authentication using a widgetadmin role, e.g. using HTTP Basic
authentication</TD>
+</TR>
+<TR>
+
+<TD> POST {wookie}/warp/ {param:widgetId, origin, subdomains} </TD>
+
+<TD> Creates a new policy with the details provided. This method requires
authentication using a widgetadmin role, e.g. using HTTP Basic
authentication.</TD>
+</TR>
+<TR>
+
+<TD> PUT {wookie}/warp/{id} {param: granted} </TD>
+
+<TD> Updates the policy specified by <EM>id</EM> with the status of
<EM>granted</EM> if the <EM>granted</EM> parameter is set to "true",
otherwise sets the status of the policy to <EM>not granted</EM>. This method
requires authentication using a widgetadmin role, e.g. using HTTP Basic
authentication.</TD>
+</TR>
+<TR>
+
+<TD> DELETE {wookie}/warp/{id} </TD>
+
+<TD> Deletes the policy specified by <EM>id</EM>. This method requires
authentication using a widgetadmin role, e.g. using HTTP Basic
authentication.</TD>
+</TR>
+</TBODY></TABLE>
+
+##Whitelist (0.9.1 only)
+
+This API is used to manage whitelist entries, which determine global access
rules for the Wookie server-side proxy.
+
+*This API was replaced by the unified Policies API in 0.9.2*
+
+<TABLE border="1"><TBODY>
+<TR>
+<TH>Request</TH>
+<TH>Description</TH>
+</TR>
+<TR>
+
+<TD> GET {wookie}/whitelist</TD>
+
+<TD> Returns all whitelist entries, consisting of an identifier and a URL.
This method requires authentication using a widgetadmin role, e.g. using HTTP
Basic authentication</TD>
+</TR>
+<TR>
+
+<TD> POST {wookie}/whitelist/ {param:url} </TD>
+
+<TD> Creates a new whitelist entry with the URL provided using the
<EM>url</EM> parameter. This method requires authentication using a widgetadmin
role, e.g. using HTTP Basic authentication.</TD>
+</TR>
+<TR>
+
+<TD> DELETE {wookie}/whitelist/{id} </TD>
+
+<TD> Deletes the whitelist entry specified by <EM>id</EM>. This method
requires authentication using a widgetadmin role, e.g. using HTTP Basic
authentication.</TD>
+</TR>
+</TBODY></TABLE>
+
+##Services (0.9.0-0.9.2)
+
+This API is used to manage services (categories) for widgets.
+
+*This API was deprecated in 0.9.1 and was removed in 0.10
+
+<table border="1"><tbody>
+<tr>
+<th >Request</th>
+<th >Description</th>
+</tr>
+<tr>
+<td > GET {wookie}/services {?locale=<em>language_tag</em>}</td>
+<td > Returns an XML document containing all services and any widgets
associated with the service category. If a locale is specified, the returned
information is localized, for example widget titles, descriptions, license
information will be in the specified language where available.</td>
+</tr>
+<tr>
+<td > GET {wookie}/services/{service_name} {?locale=<em>language_tag</em>}</td>
+<td > Returns an XML representation of the service specified by
<em>service_name</em> and all the widgets associated with it. If a locale is
specified, the returned information is localized, for example widget titles,
descriptions, license information will be in the specified language where
available.</td>
+</tr>
+<tr>
+<td > POST {wookie}/services/ {param:name} </td>
+<td > Creates a new service with the name provided using the <em>name</em>
parameter. If there is already a service with this name, a http 409 (conflict)
error is returned. This method requires authentication using a widgetadmin
role, e.g. using HTTP Basic authentication.</td>
+</tr>
+<tr>
+<td > PUT {wookie}/services/{service_name} {param:name} </td>
+<td > Renames the service specified by <em>service_name</em> with the new name
given by the <em>name</em> parameter. This method requires authentication using
a widgetadmin role, e.g. using HTTP Basic authentication.</td>
+</tr>
+<tr>
+<td > DELETE {wookie}/services/{service_name} </td>
+<td > Deletes the service specified by <em>service_name</em>. This method
requires authentication using a widgetadmin role, e.g. using HTTP Basic
authentication.</td>
+</tr>
+</tbody></table>
+
+
+ [1]: /wookie/docs/api.html
+ [2]: http://www.w3.org/TR/widgets-access/
\ No newline at end of file
Propchange: incubator/wookie/site/trunk/content/wookie/docs/api_9.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
