Wookie REST API
Skip to end of metadata
Go to start of metadata

Wookie REST API

This is a draft specification for the Wookie REST API. This is the API invoked by web applications for actions such as requesting an instance of a Widget, getting a list of available Widgets, and for managing participants and properties for Widget instances.

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

See also https://issues.apache.org/jira/browse/WOOKIE-34

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

Action

Request

Example Response

Description

 

GET {wookie}/widgetinstances

 

Not supported.

Get or Create instance

POST {wookie}/widgetinstances {params:instance_params}

<widgetdata>
<url>URL TO ACCESS WIDGET</url>
<identifier>IH6rjs75tkb6I.pl.k0hUq7YdnFcjw.eq.</identifier>
<title>Weather</title>
<height>125</height>
<width>125</width>
<maximize>false</maximize>
</widgetdata>

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.

 

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

Action

Request

Example

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

 

GET {wookie}/widgets/{service_name} {?locale=language_tag}

 

Returns an XML representation of the set of widgets that belong to the given service_name. 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.

 

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.

Services

Action

Request

Example

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.

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.

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)
  • display_name: the participant display name
  • thumbnail_url: the url of the thumbnail image for the participant

Action

Request

Example

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

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.

Action

Request

Example

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.

Labels
  • No labels