Author: scottbw
Date: Sat Nov 19 20:54:41 2011
New Revision: 1204074
URL: http://svn.apache.org/viewvc?rev=1204074&view=rev
Log:
Updated API reference providing versions the APIs apply to (See WOOKIE-235) and
moved deprecated and legacy APIs into their own section.
Modified:
incubator/wookie/site/trunk/content/wookie/docs/api.mdtext
Modified: incubator/wookie/site/trunk/content/wookie/docs/api.mdtext
URL:
http://svn.apache.org/viewvc/incubator/wookie/site/trunk/content/wookie/docs/api.mdtext?rev=1204074&r1=1204073&r2=1204074&view=diff
==============================================================================
--- incubator/wookie/site/trunk/content/wookie/docs/api.mdtext (original)
+++ incubator/wookie/site/trunk/content/wookie/docs/api.mdtext Sat Nov 19
20:54:41 2011
@@ -21,7 +21,7 @@ Notice: Licensed to the Apache Softwa
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
+# 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
@@ -79,7 +79,7 @@ If an instance already exists for the gi
</tr>
</table>
-# Widgets
+# Widgets (from 0.9.0)
##Representation
@@ -121,40 +121,7 @@ be addressed to /widgets/7. The "identif
</tr>
</tbody></table>
-
-#Services (deprecated)
-
-This API has been deprecated and support for it will be removed in future
releases.
-
-<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>
-
-
-#Participants
+#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.
@@ -195,7 +162,7 @@ Participants are represented in XML as a
</tbody></table>
-#Properties
+#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).
@@ -229,7 +196,7 @@ A property consists of a <em>propertynam
</tbody></table>
-#Flatpack
+#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.
@@ -265,9 +232,9 @@ By default the Admin REST API is secured
##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.)
-##Whitelist
+## API Keys (from 0.9.1)
-This API is used to manage whitelist entries, which determine global access
rules for the Wookie server-side proxy.
+This API is used to manage API Keys for applications accessing Wookie.
<TABLE border="1"><TBODY>
<TR>
@@ -276,31 +243,78 @@ This API is used to manage whitelist ent
</TR>
<TR>
-<TD> GET {wookie}/whitelist</TD>
+<TD> GET {wookie}/keys </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>
+<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}/whitelist/ {param:url} </TD>
+<TD> POST {wookie}/keys/ {param:apikey, email} </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>
+<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> DELETE {wookie}/whitelist/{id} </TD>
+<TD> PUT {wookie}/keys/{id} {param: apikey, email} </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>
+<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>
-##Widget Access Request Policies (WARP)
+<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][1] specification.
+*This API was replaced by the unified Policies API in 0.9.2*
+
<TABLE border="1"><TBODY>
<TR>
<TH>Request</TH>
@@ -338,9 +352,11 @@ This API is used to manage per-Widget ac
</TR>
</TBODY></TABLE>
-##API Keys
+##Whitelist (0.9.1 only)
-This API is used to manage API Keys for applications accessing Wookie.
+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>
@@ -349,29 +365,55 @@ This API is used to manage API Keys for
</TR>
<TR>
-<TD> GET {wookie}/keys </TD>
+<TD> GET {wookie}/whitelist</TD>
-<TD> Returns all API keys. This method requires authentication using a
widgetadmin role, e.g. using HTTP Basic authentication</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}/keys/ {param:apikey, email} </TD>
+<TD> POST {wookie}/whitelist/ {param:url} </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>
+<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> PUT {wookie}/keys/{id} {param: apikey, email} </TD>
+<TD> DELETE {wookie}/whitelist/{id} </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>
+<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>
-<TR>
+</TBODY></TABLE>
-<TD> DELETE {wookie}/keys/{id} </TD>
+##Services (0.9.0-0.9.2)
-<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>
+This API is used to manage services (categories) for widgets.
+*This API was deprecated in 0.9.1 and will be removed from 1.0.*
+
+<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]: http://www.w3.org/TR/widgets-access/
\ No newline at end of file
