REST post format

Question

When you use REST to create a new entry using a POST, I see some APIs such as Google's specify that you send XML as part of the request while others specify that you send key/value pairs. Is there a standard or best practice for REST POST-s?

Answer 1

It depends on the REST service implementer.

If the REST service is an adaptation of an existing html HTML form post key value pairs are generally easier to start off with.

When posting information from JavaScript it is usually easier to use JSON.

XML is used often because it is easy for humans to understand and there are heaps of tools in every language/platform that can deal with it.

Answer 2

Any representation format that works is okay, with the stipulation that you should try very hard to use standard formats such as Atom where they exist.

Update Here's a relevant quote from Roy Fielding (co-author of the HTTP standard, and the person who articulated REST in his PhD dissertation). How you design the representations used in your web service is of central importance:

A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources [...]

Be sure to read the follow-on Q&A.

Answer 3

I suggest using what is simplest because that is what REST is all about. The code snippet below is how I do a post. I know you were not looking for code specifically, but the API below (httpClient) works great. Then you decode it by using the tools we coders have always used (request.getParameter()). I believe this is what sets REST apart from SOAP. Don't make it difficult! Use HTTP!

    public void testHttpClient() {
    PostMethod pMethod = null;
    pMethod = new PostMethod("...url...");
    NameValuePair[] data = {new NameValuePair("activeFlag", "yes"), new NameValuePair("custCode", "B010"), new NameValuePair("comments", "mark is cool")};
    pMethod.setRequestBody(data);
    this.makeCall(pMethod);
}
private String makeCall(HttpMethod method) {
    String response = null;
    HttpClient client = new HttpClient();
    client.getParams().setAuthenticationPreemptive(true);
    client.getState().setCredentials(AuthScope.ANY, new UsernamePasswordCredentials(this.logon, this.pass));
    method.getParams().setParameter(HttpMethodParams.RETRY_HANDLER, new DefaultHttpMethodRetryHandler(3, false));
    method.getParams().setIntParameter(HttpMethodParams.SO_TIMEOUT, 5000);
    try {
        int statusCode = client.executeMethod(method);
        if (statusCode != HttpStatus.SC_OK) {
            System.err.println("Method failed: " + method.getStatusLine());
        }
        String aLine = null;
        StringBuffer sb = new StringBuffer();
        BufferedReader in = new BufferedReader(new InputStreamReader(method.getResponseBodyAsStream()));
        while ((aLine = in.readLine()) != null) {
            sb.append(aLine.trim());
            System.out.println(aLine);
        }
        in.close();
        response = sb.toString();
    } catch (HttpException e) {
        System.err.println("Fatal protocol violation: " + e.getMessage());
        e.printStackTrace();
    } catch (IOException e) {
        System.err.println("Fatal transport error: " + e.getMessage());
        e.printStackTrace();
    } finally {
        method.releaseConnection();
    }
    return response;
}

Answer 4

SOAP is the standard for WebServices (I think you're slightly confused bewteen WebServices and REST).

But it's really up to the implementors.