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

For more information, please explore the Attic.

This is the API reference for Wookie 0.9.0 to 0.9.2. For later versions of Wookie, see the current API docs

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 (from 0.9.0)

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

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>
Request Description
GET {wookie}/widgetinstances Not supported.
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. .
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. .
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).
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.

Widgets (from 0.9.0)

Representation

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

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

Note 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,

Request Description
GET {wookie}/widgets{?all=true, 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. (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)
GET {wookie}/widgets/{service_name} {?locale=language_tag} Returns an XML representation of the set of widgets matching the service (category) specified. (Deprecated: Removed from 0.10 onwards)
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.
POST {wookie}/widgets {file} 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

Participants (from 0.9.0)

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.

Representation

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

Request Description
GET {wookie}/participants Not supported.
GET {wookie}/participants {params: instance_params} Returns an XML representation of the Participants associated with the Widget instance specified by {instance params}.
GET {wookie}/participants {params:id_key, api_key} Returns an XML representation of the Participants associated with the Widget instance specified by {id_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.
DELETE {wookie}/participants {params: instance_params, participant_id} Deletes the specified Participant from the specified Widget Instance.

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

A property consists of a propertyname and propertyvalue.

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

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.

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 only available in latest builds, and has a number of limitations (for example, Widgets using features like Wave won't export properly).

Request Description
GET {wookie}/flatpack Not supported.
GET {wookie}/flatpack/{package_id}.wgt Downloads the specified widget package.
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.

Administration Functions

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

API Keys (from 0.9.1)

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

Request Description
GET {wookie}/keys Returns all API keys. This method requires authentication using a widgetadmin role, e.g. using HTTP Basic authentication
POST {wookie}/keys/ {param:apikey, email} Creates a new API key with the details provided. This method requires authentication using a widgetadmin role, e.g. using HTTP Basic authentication.
PUT {wookie}/keys/{id} {param: apikey, email} **NOT YET IMPLEMENTED**. Updates the API Key specified by id. This method requires authentication using a widgetadmin role, e.g. using HTTP Basic authentication.
DELETE {wookie}/keys/{id} Deletes the API key specified by id. This method requires authentication using a widgetadmin role, e.g. using HTTP Basic authentication.

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.

Request Description
GET {wookie}/policies Returns all policies. This method requires authentication using a widgetadmin role, e.g. using HTTP Basic authentication
GET {wookie}/policies/{scope} 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
POST {wookie}/policies/ 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.
DELETE {wookie}/policies/{policy} Deletes the policy specified by policy which should be a URL-encoded policy string. This method requires authentication using a widgetadmin role, e.g. using HTTP Basic authentication.

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

This API was replaced by the unified Policies API in 0.9.2

Request Description
GET {wookie}/warp {param: widgetId} Returns all access policies, or only the access policies that apply to the widget identified by the widgetId parameter. This method requires authentication using a widgetadmin role, e.g. using HTTP Basic authentication
GET {wookie}/warp/{id} Returns the access policy specified by id. This method requires authentication using a widgetadmin role, e.g. using HTTP Basic authentication
POST {wookie}/warp/ {param:widgetId, origin, subdomains} Creates a new policy with the details provided. This method requires authentication using a widgetadmin role, e.g. using HTTP Basic authentication.
PUT {wookie}/warp/{id} {param: granted} Updates the policy specified by id with the status of granted if the granted parameter is set to "true", otherwise sets the status of the policy to not granted. This method requires authentication using a widgetadmin role, e.g. using HTTP Basic authentication.
DELETE {wookie}/warp/{id} Deletes the policy specified by id. This method requires authentication using a widgetadmin role, e.g. using HTTP Basic authentication.

Whitelist (0.9.1 only)

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

Request Description
GET {wookie}/whitelist 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
POST {wookie}/whitelist/ {param:url} Creates a new whitelist entry with the URL provided using the url parameter. This method requires authentication using a widgetadmin role, e.g. using HTTP Basic authentication.
DELETE {wookie}/whitelist/{id} Deletes the whitelist entry specified by id. This method requires authentication using a widgetadmin role, e.g. using HTTP Basic authentication.

Services (0.9.0-0.9.2)

This API is used to manage services (categories) for widgets.

*This API was deprecated in 0.9.1 and was removed in 0.10

Request Description
GET {wookie}/services {?locale=language_tag} 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.
GET {wookie}/services/{service_name} {?locale=language_tag} Returns an XML representation of the service specified by service_name 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.
POST {wookie}/services/ {param:name} Creates a new service with the name provided using the name 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.
PUT {wookie}/services/{service_name} {param:name} Renames the service specified by service_name with the new name given by the name parameter. This method requires authentication using a widgetadmin role, e.g. using HTTP Basic authentication.
DELETE {wookie}/services/{service_name} Deletes the service specified by service_name. This method requires authentication using a widgetadmin role, e.g. using HTTP Basic authentication.