ability to parse POST body

I think the current implementation of the Yun REST API is a bit odd, namely in how the resource value is passed via the url string rather than in a post body.

Reading a value is correct (GET) and I have no issue here:
get the value of digital pin 13
http://myArduinoYun.local/arduino/digital/13

But setting a value is odd (POST):
set the value of pin 13
http://myArduinoYun.local/arduino/digital/13/1

I have never actually seen something like this used in a REST API (if anyone can point me to examples with backup that this is a best practice please do).

From a web client you should be able to send a POST to set the value, but the value should be in the post body, not part of the url string. For example (assuming jQuery here):

  // this is how a value should be set
  function setDigitalPin(pin, value) {
    $.ajax({
      type: "POST",
      url: "/arduino/digital/" + pin,
      data: { value: value }
    })
      .done(function (msg) {
        // handle success
      })
      .fail(function (jqXHR, textStatus) {
        // handle failure
      });
  }

// but this is the only way we can currently do it
// (which does not follow best practices)
    $.ajax({
      type: "POST",
      url: "/arduino/digital/" + pin + "/" + value
    })
      ...

I understand the way the API was structured was probably to simplify parsing on the ATmega32u4. If users want to use the API this way, that's fine, but an option to get the post body as well would be extremely helpful for people coming from a web development background.

However I think data could be included in the post body and parsed in the same way it currently is when sent in the url string. The solution would be to inspect the POST message on the linino side and if it has data in the post body (would need some constraints such as key/value pairs), then parse it into a string and append it to the end of the url string and send the new string to the ATmega32u4.

So in the jQuery ajax snippet preferred with data in the post body provided above, the YunClient would get the following string (assuming a value of 1 was passed):
"/digital/13/value/1" (similar to what you get when passing values in url but needs key/value)

This would enable people to keep using the REST API as it's currently specified on the Arduino Yun page and examples but it would also provide Web developers to POST data in the normal way. Best of both worlds IMO.

I was waiting for this message ]:smiley:

You are basically right, GET shouldn't be used to update things with REST APIs. Since there is not http method enforcement on the yun, you can use GET for http://arduino.local/arduino/digital/13 and POST for http://arduino.local/arduino/digital/13/1

I don't think we want to start the endless discussion about what's more correct, either POST or PUT, to issue updates and what an API should look like in order to be "strictly" REST compliant.
Since this discussion has already been started and people tend to give up saying "do what's best for your case", we tried to make things easier for the user.
The good thing of the way things are at the moment, is that you can play with the API using a browser. Quick and easy.