You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@wookie.apache.org by bu...@apache.org on 2012/03/23 12:33:29 UTC
svn commit: r809702 - in /websites/staging/wookie/trunk/content: ./
wookie/docs/api.html
Author: buildbot
Date: Fri Mar 23 11:33:29 2012
New Revision: 809702
Log:
Staging update by buildbot for wookie
Modified:
websites/staging/wookie/trunk/content/ (props changed)
websites/staging/wookie/trunk/content/wookie/docs/api.html
Propchange: websites/staging/wookie/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Fri Mar 23 11:33:29 2012
@@ -1 +1 @@
-1304283
+1304284
Modified: websites/staging/wookie/trunk/content/wookie/docs/api.html
==============================================================================
--- websites/staging/wookie/trunk/content/wookie/docs/api.html (original)
+++ websites/staging/wookie/trunk/content/wookie/docs/api.html Fri Mar 23 11:33:29 2012
@@ -78,9 +78,10 @@
</div>
<div id="content">
- <h1 id="api_key">API key</h1>
+ <p>For the API for earlier versions of Wookie, see the <a href="/wookie/docs/api_9.html">0.9.x API Reference</a>.</p>
+<h1 id="api-key">API key</h1>
<p>Note that except where noted, all methods require the requesting application to have a valid API key issued by the Wookie server administrator.</p>
-<h1 id="widget_instances_from_090">Widget Instances (from 0.9.0)</h1>
+<h1 id="widget-instances">Widget Instances</h1>
<p>An instance is identified using a combination of the following parameters:</p>
<ul>
<li>api_key: The key issued to a particular application</li>
@@ -126,7 +127,7 @@
<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.
+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). Note this is DEPRECATED behaviour, and future versions of the API may simply return an error code.
</td>
@@ -138,51 +139,52 @@ If an instance already exists for the gi
</tr>
</table>
-<h1 id="widgets_from_090">Widgets (from 0.9.0)</h1>
+<h1 id="widgets">Widgets</h1>
<h2 id="representation_1">Representation</h2>
<p>A Widget is currently represented in XML using an abbreviated form of the W3C Widgets packaging format:</p>
<div class="codehilite"><pre><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span>
<span class="nt"><widgets></span>
- <span class="nt"><widget</span> <span class="na">id=</span><span class="s">"7"</span> <span class="na">identifier=</span><span class="s">"http://wookie.apache.org/widgets/geo"</span> <span class="na">width=</span><span class="s">"620"</span> <span class="na">height=</span><span class="s">"660"</span> <span class="na">version=</span><span class="s">"0.1"</span><span class="nt">></span>
- <span class="nt"><title</span> <span class="na">short=</span><span class="s">""</span><span class="nt">></span>geo<span class="nt"></title></span>
+ <span class="nt"><widget</span> <span class="na">id=</span><span class="s">"http://wookie.apache.org/widgets/geo"</span> <span class="na">width=</span><span class="s">"620"</span> <span class="na">height=</span><span class="s">"660"</span> <span class="na">version=</span><span class="s">"0.1"</span><span class="nt">></span>
+ <span class="nt"><name</span> <span class="na">short=</span><span class="s">""</span><span class="nt">></span>geo<span class="nt"></title></span>
<span class="nt"><description></span>An example of a HTML 5 geolocation widget.<span class="nt"></description></span>
- <span class="nt"><icon></span>http://localhost:8080/wookie/wservices/wookie.apache.org/widgets/geo/icon.svg<span class="nt"></icon></span>
+ <span class="nt"><icon</span> <span class="na">src=</span><span class="s">"http://localhost:8080/wookie/wservices/wookie.apache.org/widgets/geo/icon.svg"</span><span class="nt">/></span>
<span class="nt"><author></span>Apache Wookie (Incubating) Team<span class="nt"></author></span>
<span class="nt"></widget></span>
<span class="nt"></widgets></span>
</pre></div>
-<p><strong>Note</strong> 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,</p>
+<p>The "id" attribute is used in other API requests.</p>
<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 > GET {wookie}/widgets{?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)
+ 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}/widgets/{service_name} {?locale=<em>language_tag</em>} </td>
-<td > 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>
+<TD> Adds a widget to the server. This method requires authentication using a widgetadmin role, e.g. using HTTP Basic authentication</TD>
+</tr>
+<tr>
+<TD> PUT {wookie}/widgets/{id} {file} </TD>
+<TD> Updates the specified widget on the server. This method requires authentication using a widgetadmin role, e.g. using HTTP Basic authentication</TD>
+</tr>
+<tr>
+<TD> DELETE {wookie}/widgets/{id} </TD>
+<TD> Deletes the specified widget on the server **and any related instances and their data**. This method requires authentication using a widgetadmin role, e.g. using HTTP Basic authentication</TD>
</tr>
</tbody></table>
-<h1 id="participants_from_090">Participants (from 0.9.0)</h1>
+<h1 id="participants">Participants</h1>
<p>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.</p>
<h2 id="representation_2">Representation</h2>
<p>Participants are represented in XML as a <participants> document, containing a <participant> element for each participant, with the attributes:</p>
@@ -218,7 +220,7 @@ be addressed to /widgets/7. The "identif
</tr>
</tbody></table>
-<h1 id="properties_from_090">Properties (from 0.9.0)</h1>
+<h1 id="properties">Properties</h1>
<p>The Properties API contains methods for both Preferences (properties affecting a single Widget Instance) and Shared Data (properties affecting sibling Widgets).</p>
<p>A property consists of a <em>propertyname</em> and <em>propertyvalue</em>.</p>
<table border="1"><tbody>
@@ -248,7 +250,7 @@ be addressed to /widgets/7. The "identif
</tr>
</tbody></table>
-<h1 id="flatpack_from_091">Flatpack (from 0.9.1)</h1>
+<h1 id="flatpack">Flatpack</h1>
<p>The Flatpack API contains methods for exporting a Widget Instance as a new Widget package (.wgt file) that can be downloaded by a client.</p>
<p>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.</p>
<p><strong>Note</strong> 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).
@@ -270,177 +272,60 @@ be addressed to /widgets/7. The "identif
<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></p>
-<h1 id="administration_functions">Administration Functions</h1>
+<h1 id="administration-functions">Administration Functions</h1>
<p>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.</p>
<h2 id="authentication">Authentication</h2>
<p>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.</p>
-<h2 id="response_formats">Response formats</h2>
+<h2 id="response-formats">Response formats</h2>
<p>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.)</p>
-<h2 id="api_keys_from_091">API Keys (from 0.9.1)</h2>
+<h2 id="api-keys">API Keys</h2>
<p>This API is used to manage API Keys for applications accessing Wookie.</p>
-<TABLE border="1"><TBODY>
+<p><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></p>
+<p><TD> GET {wookie}/keys </TD></p>
+<p><TD> Returns all API keys. This method requires authentication using a widgetadmin role, e.g. using HTTP Basic authentication</TD>
+</TR>
+<TR></p>
+<p><TD> POST {wookie}/keys/ {param:apikey, email} </TD></p>
+<p><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></p>
+<p><TD> PUT {wookie}/keys/{id} {param: apikey, email} </TD></p>
+<p><TD><strong>NOT YET IMPLEMENTED</strong>. 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></p>
+<p><TD> DELETE {wookie}/keys/{id} </TD></p>
+<p><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>
-<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>
-
-<h2 id="policies_from_092">Policies (from 0.9.2)</h2>
+</TBODY></TABLE></p>
+<h2 id="policies">Policies</h2>
<p>This API is used to manage access policies for the server-side proxy. Note that policy strings should conform to the <em>scope origin directive</em> format as described in the <code>policies</code> file.</p>
-<p><em>This API replaces the WARP and Whitelist APIs defined in 0.9.1.</em></p>
-<TABLE border="1"><TBODY>
+<p><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>
-
-<h1 id="deprecated_and_legacy_apis">Deprecated and Legacy APIs</h1>
-<h2 id="widget_access_request_policies_warp_091_only">Widget Access Request Policies (WARP) (0.9.1 only)</h2>
-<p>This API is used to manage per-Widget access request policies in accordance with the <a href="http://www.w3.org/TR/widgets-access/">W3C Widgets Access Request Policy</a> specification.</p>
-<p><em>This API was replaced by the unified Policies API in 0.9.2</em></p>
-<TABLE border="1"><TBODY>
-<TR>
-<TH>Request</TH>
-<TH>Description</TH>
+<TR></p>
+<p><TD> GET {wookie}/policies </TD></p>
+<p><TD> Returns all policies. This method requires authentication using a widgetadmin role, e.g. using HTTP Basic authentication</TD>
+</TR>
+<TR></p>
+<p><TD> GET {wookie}/policies/{scope} </TD></p>
+<p><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></p>
+<p><TD> POST {wookie}/policies/</TD></p>
+<p><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></p>
+<p><TD> DELETE {wookie}/policies/{policy} </TD></p>
+<p><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>
-<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>
-
-<h2 id="whitelist_091_only">Whitelist (0.9.1 only)</h2>
-<p>This API is used to manage whitelist entries, which determine global access rules for the Wookie server-side proxy.</p>
-<p><em>This API was replaced by the unified Policies API in 0.9.2</em></p>
-<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>
-
-<h2 id="services_090-092">Services (0.9.0-0.9.2)</h2>
-<p>This API is used to manage services (categories) for widgets.</p>
-<p>*This API was deprecated in 0.9.1 and will be removed in 0.10</p>
-<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>
+</TBODY></TABLE></p>
</div>
<div id="footer">