You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

This is a proposal for a modified API for v0.8.2 onwards, supporting the legacy API but enabling properly RESTful behaviour by clients.

Widget Instances

A widget 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"

Representation

A widget instance is represented in XML as a <widgetdata> element, containing the following elements:

  • <url> the url of the widget instance, to be used by the client to create a view of the widget instance
  • <identifier> the id key of the widget instance
  • <title> the widget title
  • <height> requested height of the widget instance, to be used by the client in creating an appropriate view
  • <width> requested width of the widget instance, to be used by the client in creating an appropriate view

GET {wookie}/widgetinstances/{instance id} {api_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 {instance params}

Returns the representation of the instance for the given parameters.

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 {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). Note this is DEPRECATED behaviour, and future versions of the API may simply return an error code.

PUT {wookie}/widgetinstances {instance params} {action}

Either stop, resume, or clone an instance, depending on the content of the action parameter.

  • No labels