...
- 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"
Action | Request | Example | Description |
---|---|---|---|
| GET {wookie}/widgetinstances |
| Not supported. |
Get or Create instance | POST {wookie}/widgetinstances {params: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. |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="7f128b97-0ecc-4f38-8fdb-9980698e7615"><ac:plain-text-body><![CDATA[ |
| 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. | ]]></ac:plain-text-body></ac:structured-macro> |
Widgets
Action | Request | Example | Description |
---|---|---|---|
| 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
Action | Request | Example | Description |
---|---|---|---|
| GET {wookie}/services |
| Returns an XML document containing all services and any widgets associated with the service category. |
| GET {wookie}/services/{service_name} |
| Returns an XML representation of the service specified by service_name and all the widgets associated with it. |
| 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.
...
- 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. |
<ac:structured-macro ac:name="unmigrated-wiki-markup |
...
" ac:schema-version="1" ac:macro-id="50993d0a-74a0-46a2-901c-b76d752c5d13"><ac:plain-text-body><![CDATA[ |
| 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. | ]]></ac:plain-text-body></ac:structured-macro> |
| 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. |