Author: scottbw
Date: Thu May 26 14:23:07 2011
New Revision: 1127933
URL: http://svn.apache.org/viewvc?rev=1127933&view=rev
Log:
Added API reference page
Added:
incubator/wookie/site/trunk/content/wookie/docs/api.mdtext (with props)
Added: 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=1127933&view=auto
==============================================================================
--- incubator/wookie/site/trunk/content/wookie/docs/api.mdtext (added)
+++ incubator/wookie/site/trunk/content/wookie/docs/api.mdtext Thu May 26
14:23:07 2011
@@ -0,0 +1,195 @@
+Title: API Reference
+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.
+
+# 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
+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>POST {wookie}/widgetinstances {params:instance_params}</td>
+<td>
+Either creates a new instance for the given parameters, or retrieves an
already-created instance. If a new instance is successfully created, the
response has a HTTP status code of 201; if an instance if successfully
retrieved, a status code of 200 is returned.
+</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
+
+
+<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 the "all=true" parameter is omitted, the
list only contains the default widgets for defined service types. 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 > Returns an XML representation of the set of widgets that belong to the
given <em>service_name</em>. For example, all widgets categorized as "weather".
(See issue WOOKIE-10). 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/{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>
+</tbody></table>
+
+
+#Services
+
+<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
+
+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
+
+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>
Propchange: incubator/wookie/site/trunk/content/wookie/docs/api.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
