Hi Mark,

Nice list of pros!

Another plus point for REST that I kinda like is that it offers huge flexibility on the client-side, spanning the spectrum from programmatic clients right down to rudimentary scripts made up of simple wget/curl calls.

On note [3] about the idempotency of POST, this is the one HTTP verb that's actually allowed have side-effects (unlike say PUT). So you'd be fine simplifying the VM creation down to a single HTTP message exchange, with the new VM's ID being returned in the as a Location header on the 201 "Created" response. Multiple POSTs would necessarily be non-idempotent, but that's fine as this is exactly the situation that the POST verb was intended for. 

Whereas if we wanted the client-side to remain in control of the resource naming, then the approach would be to use PUT and encode the client-chosen VM ID in the resource URI, e.g. your example: 

PUT /vms/XXX-XXX-XXX
  <vm>
    <name>foo</name>
  </vm>

but without the preceeding empty POST to generate the ID. This would of course only be valid if the idempotency of PUT could be preserved, i.e. there are no side-effects to VM creation (which there may well be).

So I guess my understanding of creation semantics would be to use POST (on its own) to create a subordinate resource if the identification of the new resource is to be controlled by some server-side logic, whereas PUT (also on its own) would be used if the new resource URI can be chosen by the client and there are no ill-effects arising from doing it twice.

Cheers,
Eoghan


On 30 March 2010 20:05, Mark McLoughlin <markmc@redhat.com> wrote:
Hi,

I've been reading about REST and trying to put together a convincing
list of reasons why we should choose it over SOAP:

 - There's a lot of buzz about it right now - twitter, flickr,
   facebook, S3, deltacloud etc. are all basing their APIs on it[1]

 - RHEV-M runs on JBoss and there's a significant REST push in the
   JBoss community (lead by Bill Burke) with RESTeasy, REST-* etc.

 - It makes APIs very easy to understand and play with - just look at
   some of the popular RESTful APIs ... you could imagine doing
   something fun with them after 5 minutes hacking

 - A RESTful API is largely self describing - e.g. the XML/JSON
   representation of a VM would include links for each VM action
   available

 - In theory, there should be less interoperability issues because of
   the simplicity

 - Resources are addressable - you can imagine all sorts of
   interesting possibilities from being able to pass around a URL for
   a VM, for example

 - Easier to consume RESTful APIs in AJAX apps

And then there are a whole heap of advantages REST advocates shout about
which I'm finding hard to get excited/convinced by:

 - Because you're not abusing HTTP as a transport protocol, standard
   HTTP constructs can be used - caching, proxies, gateways etc.

 - The web scales really well, so RESTful APIs will naturally scale too

And some disadvantages:

 - At first, it looks trivial to design a good RESTful API ... but the
   more I read, the more really subtle issues[3] there are to think
   about - you only need to look at all the controversies about
   various APIs being denounced as not truly RESTful

 - Similarly, what we essentially want is an RPC API, but thinking
   about REST as just another API protocol almost guarantees you'll do
   it wrong

 - It doesn't look like there is the same level of auto-generated
   client bindings available as there is with SOAP/WSDL[4]

Perhaps it's just a case of being turned off REST by the elevated levels
of hype and the angst-ridden battles going on over just what is and
isn't RESTful[5]

Cheers,
Mark.


[1] - Well, they claim to be - and then at least some of them are
denounced as being not "truly" RESTful

[2] - Nice where certain actions are only available to certain users,
now thank I think about it

[3] - Simple example - POST apparently should be idempotent, so for the
"create VM" API, do you require the client to generate an ID and ensure
reject multiple requests with that API e.g.

=> POST /vms/
  <vm>
    <id>XXX-XXX-XXX</id>
    <name>foo</name>
  </vm>

or do you have POST generate an ID, which you then PUT to:

=> POST /vms/

<= HTTP/1.1 200 OK
  Location: /vms/XXX-XXX-XXX

=> PUT /vms/XXX-XXX-XXX
  <vm>
    <name>foo</name>
  </vm>

[4] - Although ... my guess is the auto-generated bindings are never
that nice and wrapping the auto-generated binding with a more natural
API for the language would be a similar job as wrapping a REST API

[5] - e.g. I find it very hard to see why I should care about most of
the points here:

 http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

_______________________________________________
rhevm-api mailing list
rhevm-api@lists.fedorahosted.org
https://fedorahosted.org/mailman/listinfo/rhevm-api