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 strawman for 0.8.2
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 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"
GET {wookie}/widgetinstances
Not supported.
POST {wookie}/widgetinstances {instance params}
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 {instance params} {action}
Either stop, resume, or clone an instance, depending on the content of the action parameter.
Widgets
GET {wookie}/widgets{?all=true}
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.
GET {wookie}/widgets/{service_name}
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)
GET {wookie}/widgets/{id}
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.
Services
GET {wookie}/services
Returns all services and their default widgets. NOT YET IMPLEMENTED.
GET {wookie}/services/{service_name}
Returns XML representation of the service specified by service_name and the widgets associated with it. NOT YET IMPLEMENTED.
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
GET {wookie}/participants
Not supported.
GET {wookie}/participants {instance params}
Returns an XML representation of the Participants associated with the Widget instance specified by {instance params}.
POST {wookie}participants {instance params}{participant params}
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 {instance params}{participant params}
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.
GET {wookie}/properties
Not supported.
GET {wookie}/properties {instance params}{propertyname}
Returns the value of the specified property for the specified instance.
POST {wookie}/properties {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 {instance params}{propertyname}{propertyvalue}
Updates the value of the specified property of the specified Widget Instance. NOT YET IMPLEMENTED.
DELETE {wookie}/properties {instance params}{propertyname}
Deletes a property. NOT YET IMPLEMENTED