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

For more information, please explore the Attic.

API Reference

General¶

• Home
• News
• Download
• License

Documentation¶

• Download and Quickstart
• Server Admin
• Embedding
• Integrating with Shindig
• Building widgets
• FAQ
• API Reference

Community¶

• Get Involved
• Mailing Lists
• People

Development¶

• Getting Started
• Running
• Widget Templates
• Extension Features
• Deploying Widgets
• Environment
• Release Management
• Issue Tracker
• Management
• W3C Widget Parser

ASF¶

• Apache Software Foundation
• Thanks
• Become a Sponsor
• Security

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:

• 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
• locale: The preferred locale of the widget, expressed using a BCP47 Language Tag

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>

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.

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:

• id: the participant id (not to be confused with Wookie's internal id of a participant)
• display_name: the participant display name
• thumbnail_url: the url of the thumbnail image for the participant

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>

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

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>

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>

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.