[WOOKIE-34] Accept/reject REST API proposal for getting/creating widgets

• Type: Improvement
• Status: Resolved
• Priority: Critical
• Resolution: Fixed
• Affects Version/s: 0.9.0
• Fix Version/s: 0.9.1
• Assignee: Unassigned
• Reporter: Ross Gardler
• Created: 14/Sep/09 09:54
• Updated: 05/Oct/11 12:18
• Resolved: 05/Oct/11 12:18

Description

A while ago we proposed making changes to the Widget Instances API to be more REST-like in its behaviour, while still supporting legacy clients.

The main changes are (1) the addition of GET methods to retrieve a Widget Instance already created and (2) a change in documentation for the POST method to offer a deprecation warning for using it as get-or-create. (PUT is not altered).

Proposed changes to the API:

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

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

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

Issue Links

• blocks: WOOKIE-18 Write Plugin developers guide