On 28/02/2010 09:52, Scott Wilson wrote:
On 28 Feb 2010, at 00:30, Ross Gardler wrote:
In my opinion the REST API needs to be improved, as it stands it is
not very RESTful. A RESTful API uses the HTTP methods as follows:
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
There are currently many places where these methods are used
incorrectly and thus confusingly.
Before heading off down the route of redefining the REST API I'd like
to understand if it is used or not.
...
Can we consider rebuilding it now before people start to adopt it?
Should we instead adopt a deprecate and replace approach?
I'm also not clear whether what you are suggesting is a change to the
API specification:
http://incubator.apache.org/wookie/wookie-rest-api.html
Or to its implementation?
The implementation is confusing (tackled in another thread) but the
actual API specification is not RESTful as it currently stands. If we
read over the API as it is currently specified there are quite a few
places where the HTTP methods are used incorrectly. Correct use (as
posted above) is:
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.
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.
As an example of the kind of problem I see:
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.
We already have some proposed changes for the widgetinstance API at
http://cwiki.apache.org/confluence/display/WOOKIE/strawman+for+0.8.2
Ross
