Interesting that no-one is yet willing to weigh on SOAP's side :-)
Methinks it's time to experiment with a REST version ...
On Wed, 2010-03-31 at 03:15 +0200, Geert Jansen wrote:
...
So the question should really be: does a RHEV API map best to an RPC
architectural style, or to REST? One this question is answered, the
decision for SOAP or REST then becomes trivial.
That's a good way to look at it
In my view, RHEV maps best to REST, because the resources involved in
it
are quite complicated, but the operations on them and their
relationships aren't. For example, the VM object in my REST api has 29
fields at the moment. But i only have 4 HTTP methods that operate on it
(GET, POST, PUT, DELETE), and only two relationships (parent-of,
child-of, both expressed by URLs).
In an RPC model, we would either have 29 getter/setter methods, or we
would be passing around a 29-field structure, or maybe we'd have a
generic "set key/value pair" call. None of these approaches seems very
clean to me.
Well, with SOAP, we'd have a VM "complex type" containing the 29 fields,
so we wouldn't have 29 RPC getter/setter RPC. So, I don't see this being
a big difference between the SOAP and REST styles.
It's when you think about the operations on the resources that I think
it's less clear REST is an obvious mapping.
There's other minor advantages to me of REST over SOAP, notably
the
simplicity of the API, and triviality of the client. But my main
argument is that REST maps RHEV more naturally.
Responding to a two of your points:
* REST look trivial at first sight.. but it's not.
Fully agreed here. In my view and experience, designing a good REST API
is much more difficult than an RPC API. And in this case, the design
effort is inversely proportional to the simplicity of the result. I
think that is desirable.
Yep, agreed.
* What we essentially want is RPC..
Don't agree on this one. If we do the design of this properly, the
resulting API is actually much more natural for REST than for RPC.
I was more thinking of the likes of our VM control commands - start,
stop, shutdown, migrate etc. IMHO, they are essentially RPCs and don't
fit all that naturally to REST
The deltacloud way of doing this is that its instance description has a
set of action URLs which you can post to, one for each instance control
command
In your API, it looks like you post the command name and parameters to a
"/vms/{id}/command" URL, right?
I think both ways are fine, but I'm not convinced that either is really
RESTful according to Fielding's view of the world. Maybe that doesn't
matter, though?
Eoghan had an interesting suggestion on irc. These control commands are
essentially requests for the VM to transition state, so perhaps this
makes more sense:
GET /vms/XXXX
<vm>
<id>XXXX</id>
<name>foo</id>
<state>RUNNING</state>
</vm>
PUT /vms/XXXX
<vm>
<state>SHUTDOWN</state>
</vm>
PUT /vms/XXXX
<vm>
<host>barfoo.devel.redhat.com</host>
</vm>
However, things get sticky when you think about:
- A request to shutdown might be ignored - e.g. the user might
dismiss the shutdown dialog in the guest
- A request to reboot isn't really a state transition request unless
we explicitly make REBOOTING a state
- These requests might take a long time to complete, so it might make
sense to return 202 Accepted and allow the client to poll for
completion
- The requests might accept parameters that do not belong in the
representation of a VM itself
Cheers,
Mark.