You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@wookie.apache.org by Ross Gardler <rg...@apache.org> on 2010/02/28 01:30:10 UTC
Reviewing the REST API
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.
My suspicion is that it is not used a great deal (indeed in trying to
use it this last few days I have found that parts of it just don't
work). Examining the Moodle plugin the REST API is not used at all
(there are todo items all over it to change the code to use the REST API).
Can we consider rebuilding it now before people start to adopt it?
Should we instead adopt a deprecate and replace approach?
Ross
Re: Reviewing the REST API
Posted by Ross Gardler <rg...@apache.org>.
On 28/02/2010 15:42, 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.
>>
>> My suspicion is that it is not used a great deal (indeed in trying to
>> use it this last few days I have found that parts of it just don't
>> work). Examining the Moodle plugin the REST API is not used at all
>> (there are todo items all over it to change the code to use the REST API).
>>
>> Can we consider rebuilding it now before people start to adopt it?
>> Should we instead adopt a deprecate and replace approach?
>>
>> Ross
>
> Looking at the connector framework code I think I found the problem -
> you expected POST participants/ {params} to return some XML. It doesn't,
> it just returns a status code (201 if created, 200 if unchanged, etc).
>
> Removing the code that attempts to parse the response body as an XML
> document removes the problem, and the REST API works just fine:
Well duh!
Thanks for reminding me why release early, release often is important in
open source. Thanks also for fixing it and helping me get to the
important new multi-user demo code working as a result.
[this does not affect my request to reconsider the RESTfullness of our
API - just proves there is nothing broken in the current implementaiton]
Ross
Re: Reviewing the REST API
Posted by Scott Wilson <sc...@gmail.com>.
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.
>
> My suspicion is that it is not used a great deal (indeed in trying
> to use it this last few days I have found that parts of it just
> don't work). Examining the Moodle plugin the REST API is not used at
> all (there are todo items all over it to change the code to use the
> REST API).
>
> Can we consider rebuilding it now before people start to adopt it?
> Should we instead adopt a deprecate and replace approach?
>
> Ross
Looking at the connector framework code I think I found the problem -
you expected POST participants/ {params} to return some XML. It
doesn't, it just returns a status code (201 if created, 200 if
unchanged, etc).
Removing the code that attempts to parse the response body as an XML
document removes the problem, and the REST API works just fine:
public void addParticipant(WidgetInstance widget, User user) throws
WookieConnectorException {
StringBuilder postdata;
try {
postdata = new StringBuilder("api_key=");
postdata.append(URLEncoder.encode(getConnection().getApiKey(),
"UTF-8"));
postdata.append("&shareddatakey=");
postdata.append(URLEncoder.encode(getConnection().getSharedDataKey(),
"UTF-8"));
postdata.append("&userid=");
postdata.append(URLEncoder.encode(getCurrentUser().getLoginName(),
"UTF-8"));
postdata.append("&widgetid=");
postdata.append(URLEncoder.encode(widget.getId(), "UTF-8"));
postdata.append("&participant_id=");
postdata.append(URLEncoder.encode(user.getLoginName(), "UTF-8"));
postdata.append("&participant_display_name=");
postdata.append(URLEncoder.encode(user.getScreenName(),
"UTF-8"));
postdata.append("&participant_thumbnail_url=");
postdata.append(URLEncoder.encode(user.getThumbnailUrl(),
"UTF-8"));
} catch (UnsupportedEncodingException e) {
throw new WookieConnectorException("Must support UTF-8
encoding", e);
}
URL url = null;
try {
url = new URL(conn.getURL() + "/participants");
HttpURLConnection conn = (HttpURLConnection)url.openConnection();
conn.setDoOutput(true);
OutputStreamWriter wr = new
OutputStreamWriter(conn.getOutputStream());
wr.write(postdata.toString());
wr.flush();
if (conn.getResponseCode() > 201) throw new IOException();
} catch (MalformedURLException e) {
throw new WookieConnectorException("Participants rest URL is
incorrect: " + url, e);
} catch (IOException e) {
StringBuilder sb = new StringBuilder("Problem adding a
participant. ");
sb.append("URL: ");
sb.append(url);
sb.append(" data: ");
sb.append(postdata);
throw new WookieConnectorException(sb.toString(), e);
}
}
S
Re: Reviewing the REST API
Posted by Scott Wilson <sc...@gmail.com>.
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.
>
> 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
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
Re: Reviewing the REST API
Posted by Ross Gardler <rg...@apache.org>.
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
Re: Reviewing the REST API
Posted by Scott Wilson <sc...@gmail.com>.
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.
>
> My suspicion is that it is not used a great deal (indeed in trying
> to use it this last few days I have found that parts of it just
> don't work). Examining the Moodle plugin the REST API is not used at
> all (there are todo items all over it to change the code to use the
> REST API).
>
> 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?
If the former then the first step should be documenting the proposed
spec before rewriting any code.
If the latter I suggest starting with the test cases. These cover the
methods concerned and currently these all pass so we need to see have
cases that identify broken behaviour.
>
> Ross