Re: Reviewing the REST API

[Scott Wilson]

On 1 Mar 2010, at 15:03, Ross Gardler wrote:

On 28/02/2010 09:52, Scott Wilson wrote:

On 28 Feb 2010, at 00:30, Ross Gardler wrote:

POST is used to create a resource on the server
GET is used to retrieve a resource
PUT is used to change the state of a resource or to update it
DELETE is used to remove or delete a resource

If the former then the first step should be documenting the proposed
spec before rewriting any code.

As an example of the kind of problem I see:







We already have some proposed changes for the widgetinstance API at 
http://cwiki.apache.org/confluence/display/WOOKIE/strawman+for+0.8.2

I agree, to an extent. I'm no fan of designing things that we might not need. I'd rather get on with implementing what we actually need now, rather than what we anticipate we *might* need tomorrow. I'm happy do this as part of my work on the connector framework. What I'm trying to understand is whether there is general agreement that the REST API is in need of rewriting and if we do agree on this how much effort do we need to put into backward compatability. A DELETE to participants does not delete a participant resource, it removes the participant from a widgetinstance resource. This action is an update to a Widgetinstance resource and thus should be a POST to widgetinstance. A less clear example is a POST to participants does not create/ update a participant resource, it updates a widgetinstance resource. In this case it can be argued that the participant is being modified too, it's only knowledge of the way it is implemented that brings me to the above conclusion. However, I would suggest that if the first example is valid, then to keep things consistent this would be valid too. Making these changes then frees up a POST to participant to create a new participant resource. We might want to do this, for example, when we want to maintain lists of potential participants as opposed to actual participants.

Got it. Yes, the API isn't purely RESTful - many of the actions actually modify instances in various ways. E.g., rather than a POST to /participants/ to add a participant to an instance it would make more sense in REST terms to POST a representation of a Participant to an instance resource URL and then get a URL like /widgetinstances/4/ participants/1 returned as a target for subsequent PUT/GET/DELETE operations on that participant. The strawman proposal goes some way towards making this easier by proposing widget instance ids - I was a bit hesitant on this as the design as it stands is very robust, as even if you swap out a Wookie server for another one, generally speaking everything still works as there are no object id dependencies (e.g. if you switch container to another Wookie installation with the same widgets installed as before, you just get a new instance rather than a load of 404s for your existing contexts).

Ross

smime.p7s
Description: S/MIME cryptographic signature