Re: Reviewing the REST API

[Scott Wilson]

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









Ross

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?

    StringBuilder postdata;
    try {
      postdata = new StringBuilder("api_key=");

      postdata.append("&shareddatakey=");

      postdata.append("&userid=");

      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("&participant_thumbnail_url=");

    } catch (UnsupportedEncodingException e) {

    }

    URL url = null;
    try {
      url = new URL(conn.getURL() + "/participants");
      HttpURLConnection conn = (HttpURLConnection)url.openConnection();
      conn.setDoOutput(true);

      wr.write(postdata.toString());
      wr.flush();
      if (conn.getResponseCode() > 201) throw new IOException();
    } catch (MalformedURLException e) {

    } catch (IOException e) {

      sb.append("URL: ");
      sb.append(url);
      sb.append(" data: ");
      sb.append(postdata);
      throw new WookieConnectorException(sb.toString(), e);
    }
  }

S

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 { postdata.append(URLEncoder.encode(getConnection().getApiKey(), "UTF-8")); postdata.append(URLEncoder.encode(getConnection().getSharedDataKey(), "UTF-8")); postdata.append(URLEncoder.encode(getCurrentUser().getLoginName(), "UTF-8")); postdata.append(URLEncoder.encode(user.getScreenName(), "UTF-8")); postdata.append(URLEncoder.encode(user.getThumbnailUrl(), "UTF-8")); throw new WookieConnectorException("Must support UTF-8 encoding", e); OutputStreamWriter wr = new OutputStreamWriter(conn.getOutputStream()); throw new WookieConnectorException("Participants rest URL is incorrect: " + url, e); StringBuilder sb = new StringBuilder("Problem adding a participant. ");

smime.p7s
Description: S/MIME cryptographic signature