Author: scottbw
Date: Fri Mar 23 11:51:23 2012
New Revision: 1304289
URL: http://svn.apache.org/viewvc?rev=1304289&view=rev
Log:
Simplified authn information in the API doc
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=1304289&r1=1304288&r2=1304289&view=diff
==============================================================================
--- incubator/wookie/site/trunk/content/wookie/docs/api.mdtext (original)
+++ incubator/wookie/site/trunk/content/wookie/docs/api.mdtext Fri Mar 23
11:51:23 2012
@@ -18,12 +18,19 @@ Notice: Licensed to the Apache Softwa
For the API for earlier versions of Wookie, see the [0.9.x API Reference][1].
-# API key
+# Authentication
+### API keys
+Some methods require the requesting application to have a valid API key issued
by the Wookie server administrator.
-Note that except where noted, all methods require the requesting application
to have a valid API key issued by the Wookie server administrator.
+### HTTP Basic 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.
# Widget Instances
+
+The Widget Instances API is used to request an instance of a Widget for a
particular viewer in a particular context.
+
+###Instance Parameters
An instance is identified using a combination of the following parameters:
- api_key: The key issued to a particular application
@@ -32,7 +39,7 @@ An instance is identified using a combin
- widgetid: The URI of the widget this is an instance of
- locale: The preferred locale of the widget, expressed using a BCP47 Language
Tag
-##Representation
+###Representation
An instance is represented in XML as follows:
@@ -48,21 +55,19 @@ An instance is represented in XML as fol
<tr>
<th>Request</th>
<th>Description</th>
-</tr>
-
-<tr>
- <td>GET {wookie}/widgetinstances</td>
- <td>Not supported.</td>
+ <th>Authentication</th>
</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>
+ <td>API key</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>
+ <td>API key</td>
</tr>
<tr>
@@ -72,17 +77,21 @@ Create a new widget instance using the g
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>
+ <td>API key</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>
+ <td>API key</td>
</tr>
</table>
# Widgets
-##Representation
+The Widgets API is used to get the list of available widgets, information
about a specific widget. For administrators, this API is also used to manage
widgets, including installing, updating and deleting.
+
+###Representation
A Widget is currently represented in XML using an abbreviated form of the W3C
Widgets packaging format:
@@ -102,28 +111,34 @@ The "id" attribute is used in other API
<tr>
<th >Request</th>
<th >Description</th>
+ <th>Authentication</th>
</tr>
<tr>
<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.
</td>
+<td>Not required</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>
+<td>Not Required</td>
</tr>
<tr>
<TD> POST {wookie}/widgets {file} </TD>
-<TD> Adds a widget to the server. This method requires authentication using a
widgetadmin role, e.g. using HTTP Basic authentication</TD>
+<TD> Adds a widget to the server. The method echoes the widget metadata in the
response.</TD>
+<td>Admin credentials</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>
+<TD> Updates the specified widget on the server. </TD>
+<td>Admin credentials</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>
+<TD> Deletes the specified widget on the server **and any related instances
and their data**.</TD>
+<td>Admin credentials</td>
</tr>
</tbody></table>
@@ -144,6 +159,7 @@ Participants are represented in XML as a
<tr>
<th >Request</th>
<th >Description</th>
+ <th>Authentication</th>
</tr>
<tr>
<td >GET {wookie}/participants </td>
@@ -152,18 +168,22 @@ Participants are represented in XML as a
<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>
+<td>API key</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>
+<td>API 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>
+<td>API key</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>
+<td>API key</td>
</tr>
</tbody></table>
@@ -178,26 +198,27 @@ A property consists of a <em>propertynam
<tr>
<th >Request</th>
<th >Description</th>
-</tr>
-<tr>
-<td >GET {wookie}/properties</td>
-<td >Not supported.</td>
+ <th>Authentication</th>
</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>
+<td>API key</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>
+<td>API key</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>
+<td>API key</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>
+<td>API key</td>
</tr>
</tbody></table>
@@ -213,18 +234,17 @@ This can be used, for example, for a plu
<tr>
<th >Request</th>
<th >Description</th>
-</tr>
-<tr>
-<td >GET {wookie}/flatpack</td>
-<td >Not supported.</td>
+ <th>Authentication</th>
</tr>
<tr>
<td >GET {wookie}/flatpack/{package_id}.wgt</td>
<td >Downloads the specified widget package.</td>
+<td>Not required</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>
+<td>API key</td>
</tr>
</tbody></table>
@@ -232,9 +252,6 @@ This can be used, for example, for a plu
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.)
@@ -246,30 +263,33 @@ This API is used to manage API Keys for
<TR>
<TH>Request</TH>
<TH>Description</TH>
+ <th>Authentication</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>
+<TD> Returns all API keys. </TD>
+<td>Admin credentials</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>
+<TD> Creates a new API key with the details provided</TD>
+<td>Admin credentials</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>
+<TD>**NOT YET IMPLEMENTED**. Updates the API Key specified by <EM>id</EM>./TD>
+<td>Admin credentials</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>
+<TD> Deletes the API key specified by <EM>id</EM></TD>
+<td>Admin credentials</td>
</TR>
</TBODY></TABLE>
@@ -282,30 +302,35 @@ This API is used to manage access polici
<TR>
<TH>Request</TH>
<TH>Description</TH>
+ <th>Authentication</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>
+<TD> Returns all policies.</TD>
+<td>Admin credentials</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>
+<TD> Returns policies matching the specified scope (e.g. a URL-encoded Widget
URI).</TD>
+<td>Admin credentials</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>
+<TD> Creates a new policy using a policy string supplied in the body of the
POST message. </TD>
+<td>Admin credentials</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>
+<TD> Deletes the policy specified by <EM>policy</EM> which should be a
URL-encoded policy string.</TD>
+<td>Admin credentials</td>
</TR>
</TBODY></TABLE>
