2016/04/10 - Apache Wookie has been retired.

For more information, please explore the Attic.

This is the documentation for Wookie 0.10 and later. For the API for earlier versions of Wookie, see the 0.9.x API Reference.

Authentication

API keys

Some 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.

Response formats

Clients may request a response in either XML or JSON by setting the appropriate request content type using the Accepts header. 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.

Note that as of Wookie 0.10.0 not all APIs have yet been updated to supply JSON responses.

Widget Instances

The Widget Instances API is used to request an instance of a Widget for a particular viewer in a particular context.

An instance is identified using a combination of the following parameters:

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>
Request Description Authentication
GET {wookie}/widgetinstances/{instance id_key} 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. . API key
GET {wookie}/widgetinstances/ {params:instance_params} 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. . API key
POST {wookie}/widgetinstances {params:instance_params} 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. API key
PUT {wookie}/widgetinstances {params:instance_params, action, [cloneshareddatakey]} 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. API key

Widgets

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.

A Widget is represented in XML using an abbreviated form of the W3C Widgets packaging format:

<?xml version="1.0" encoding="UTF-8"?>
<widgets>
    <widget id="http://wookie.apache.org/widgets/geo" width="620" height="660" version="0.1">
        <name short="">geo</title>
        <description>An example of a HTML 5 geolocation widget.</description>
        <icon src="http://localhost:8080/wookie/wservices/wookie.apache.org/widgets/geo/icon.svg"/>
        <author>Apache Wookie (Incubating) Team</author>
    </widget>
</widgets>

The "id" attribute is used in other API requests.

Request Description Authentication
GET {wookie}/widgets{?locale=language_tag} 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. Not required
GET {wookie}/widgets/{id} {?locale=language_tag} Returns an XML representation of the widget with the specified id. Note that in the current release this is the actual database key; future releases should implement this using the widget URI as the id. 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. Not Required
POST {wookie}/widgets {file} Adds a widget to the server. The method echoes the widget metadata in the response. Admin credentials
PUT {wookie}/widgets/{id} {file} Updates the specified widget on the server. Admin credentials
DELETE {wookie}/widgets/{id} Deletes the specified widget on the server **and any related instances and their data**. Admin credentials

Participants

A Participant consists of a participant_display_name, participant_id, and participant_thumbnail_url. 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.

Participants are represented in XML as a <participants> document, containing a <participant> element for each participant, with the attributes:

For example:

GET http://localhost:8080/wookie/participants?id_key=j5GGdhIQViNCRTWg5wnSrccDaks.eq.&api_key=TEST

<participants>
  <participant id="testuser" display_name="First Test User" thumbnail_url=""/>
  <participant id="testuser2" display_name="Second Test User" thumbnail_url=""/>
</participants>
Request Description Authentication
GET {wookie}/participants {params: instance_params} Returns an XML representation of the Participants associated with the Widget instance specified by {instance params}. API key
GET {wookie}/participants {params:id_key, api_key} Returns an XML representation of the Participants associated with the Widget instance specified by {id_key}. API key
POST {wookie}participants {params: instance_params, participant_id, participant_display_name, participant_thumbnail_url} 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. API key
DELETE {wookie}/participants {params: instance_params, participant_id} Deletes the specified Participant from the specified Widget Instance. API key

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 propertyname and propertyvalue.

Example:

GET http://localhost:8080/wookie/properties?id_key=AoK9uakcv4M.pl.jRTcgQs3x4D0jrs.eq.&api_key=TEST&propertyname=city

manchester
Request Description Authentication
GET {wookie}/properties {params: instance_params, propertyname} Returns the value of the specified property for the specified instance. API key
POST {wookie}/properties {params: instance_params, propertyname, propertyvalue, [is_public=true]} 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. API key
PUT {wookie}/properties {params: instance_params, propertyname, propertyvalue} Updates the value of the specified property of the specified Widget Instance. API key
DELETE {wookie}/properties {params: instance_params, propertyname} Deletes a property. This method returns a 404 status code if there is no matching property. API key

API Keys

This API is used to manage API Keys for applications accessing Wookie.

<keys>
  <key id="401" value="TEST" email="test@127.0.0.1"/>
</keys>
Request Description Authentication
GET {wookie}/keys Returns all API keys. Admin credentials
POST {wookie}/keys/ {param:apikey, email} Creates a new API key with the details provided Admin credentials
PUT {wookie}/keys/{id} {param: apikey, email} **NOT YET IMPLEMENTED**. Updates the API Key specified by id./TD> Admin credentials
DELETE {wookie}/keys/{id} Deletes the API key specified by id Admin credentials

Policies

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.

Example:

GET http://localhost:8080/wookie/policies

<policies>
<policy scope="http://wookie.apache.org/widgets/freeder" origin="*" directive="ALLOW"/>
<policy scope="http://www.getwookie.org/widgets/weather" origin="http://newsrss.bbc.co.uk:80" directive="ALLOW"/>
<policy scope="*" origin="http://127.0.0.1" directive="ALLOW"/>
<policy scope="*" origin="http://localhost:8080" directive="ALLOW"/>
<policy scope="*" origin="http://*.apache.org" directive="ALLOW"/>
</policies>
Request Description Authentication
GET {wookie}/policies Returns all policies. Admin credentials
GET {wookie}/policies/{scope} Returns policies matching the specified scope (e.g. a URL-encoded Widget URI). Admin credentials
POST {wookie}/policies/ Creates a new policy using a policy string supplied in the body of the POST message. Admin credentials
DELETE {wookie}/policies/{policy} Deletes the policy specified by policy which should be a URL-encoded policy string. Admin credentials

Flatpack (unstable)

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, and has a number of limitations (for example, Widgets using features like Wave won't export properly). For this reason this API is flagged as unstable and may change in future releases.

Request Description Authentication
GET {wookie}/flatpack/{package_id}.wgt Downloads the specified widget package. Not required
POST {wookie}/flatpack {params: instance_params creates a new W3C Widget package (.wgt) with an opaque file name for the specified widget instance, and returns the download URL. API key