[vdsm] RESTful VM creation

Adam Litke agl at us.ibm.com
Wed May 16 14:19:59 UTC 2012


Thanks for your comments! ...

On Wed, May 16, 2012 at 03:45:46PM +0200, Geert Jansen wrote:
> Hi Adam,
> 
> i didn't go into detail but just a few words on these mappings below:
> 
> >>    POST /api/vms/define - Define a new VM in the system
> >>    POST /api/vms/<id>/disks/add - Add a new disk to the VM
> >>    POST /api/vms/<id>/cdroms/add - Add a cdrom
> >>    POST /api/vms/<id>/nics/add - Add a NIC
> 
> In most RESTful APIs this would just be a POST to the collection
> (/api/vms, cdroms, and nics). POST has implicit "add to" semantics,
> so the "add" and "define" are not needed.

I am trying to be compatible with the engine REST API because I want to use the
same sdk and cli tools for both server endpoints.  Given this, I would like to
follow the engine model.  Is a POST to the collection for 'create' the engine
way?

The main problem I am hitting is that vdsm has no api to define (but not start)
a vm.  So currently, a single call must fully specify the vm.  After this call
the vm is started.  What I need for rest is a way to manipulate a vm definition
before starting it.  This is the contentious part.

> >>    PUT /api/vms/<id>  - Change boot sequence
> 
> I would suggest PATCH if the semantics are to update part of the
> entity, and PUT if you are updating the entire entities. PATCH vs
> PUT can become confusing. In the RHEV-M API we decided that PUT ==
> PATCH, and it led to all kinds of issues. For example, say you want
> to update the boot sequence. How do you differentiate between adding
> a boot device, and replacing the list of boot devices with a 1-list
> entry.

Would like to use the engine method (even if it is not optimal) because
compatibility is important.

> >>    POST /api/vms/<id>/start - Boot the VM
> 
> Yes, we called these "actions" in the RHEV-M API. They are a
> last-resort RPC-ism that you can use in case the thing you're trying
> to do does not cleanly fit into the RESTful paradigm. In this case,
> starting a VM could have been modeled by a PATCH that sets
> status=off to status=on. But for a shutdown, there's multiple state
> transitions that go from state=on to state=off (e.g. shutdown vs
> power off). Therefore in this case an action is the best solution in
> my view.
> 
> One of my pet peeves in the RHEV-M API development was that instead
> of the above, we'd do a:
> 
> POST /api/vms/<id>/actions, with an action resource that has a
> command=start attribute. In the end we didn't go for this, but i
> think it would have been slightly more RESTful.

Yep, I realize some mistakes might have been made, but then again, REST isn't
perfect.  You have to find something that works.  I think the engine API works
pretty well and I am happy to use it as a model.

> Finally, i would highly recommend JSON as your serialization format
> and not XML. Not sure if you were planning to do that.

I support both JSON and XML.  JSON is much nicer, but the sdk and cli programs
want to talk xml so I support it too.

> I did do a write up of some of the learnings we had during the
> development of the RHEV-M API. That link is here:
> 
> http://readthedocs.org/docs/restful-api-design/en/latest/
> 
> There's a few things that should be updated in the link above but i
> haven't come around doing that yet. In case you haven't ready
> Fieldings "REST APIs must be hypertext-driven", i would highly
> recommend that.

I have read through this before and found it to be very helpful. Thanks!

-- 
Adam Litke <agl at us.ibm.com>
IBM Linux Technology Center



More information about the vdsm-devel mailing list