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.

>>    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.

>>    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.

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

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.

Regards,
Geert




>>




On 05/16/2012 03:19 PM, Adam Litke wrote:
No comments at all on this??

On Wed, May 09, 2012 at 09:35:29AM -0500, Adam Litke wrote:
I would like to discuss a problem that is going to affect VM creation in the new
REST API.  This topic has come up previously and I want to revive that
discussion because it is blocking a proper implementation of VM.create().

Consider a RESTful VM creation sequence:
   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
   PUT /api/vms/<id>  - Change boot sequence
   POST /api/vms/<id>/start - Boot the VM

Unfortunately this is not possible today with vdsm because a VM must be
fully-specified at the time of creation and it will be started immediately.

As I see it there are two ways forward:

1.) Deviate from a REST model and require a VM resource definition to include
all sub-collections inline.
-- or --
2.) Support storage of vm definitions so that powered off VMs can be manipulated
by the API.

My preference would be #2 because: it makes the API more closely follow RESTful
principles, it maintains parity with the cluster-level VM manipulation API, and
it makes the API easier to use in standalone mode.

Here is my idea on how this could be accomplished without committing to stateful
host storage.  In the past we have discussed adding an API for storing arbitrary
metadata blobs on the master storage domain.  If this API were available we
could use it to create a transient VM "construction site".  Let's walk through
the above RESTful sequence again and see how my idea would work in practice:

* POST /api/vms/define - Define a new VM in the system
A new VM definition would be written to the master storage domain metadata area.

* GET /api/vms/<new-uuid>
The normal 'list' API is consulted as usual.  The VM will not be found there
because it is not yet created.  Next, the metadata area is consulted.  The VM is
found there and will be returned.  The VM state will be 'New'.

* POST /api/vms/<id>/disks/add - Add a new disk to the VM
For 'New' VMs, this will update the VM metadata blob with the new disk
information.  Otherwise, this will call the hotplugDisk API.

* POST /api/vms/<id>/cdroms/add - Add a cdrom
For 'New' VMs, this will update the VM metadata blob with the new cdrom
information.  If we want to support hotplugged CDROMs we can call that API
later.

* POST /api/vms/<id>/nics/add - Add a NIC
For 'New' VMs, this will update the VM metadata blob with the new nic
information.  Otherwise it triggers the hotplugNic API.

* PUT /api/vms/<id>  - Change boot sequence
Only valid for 'New' VMs.  Updates the metadata blob according to the parameters
specified.

* POST /api/vms/<id>/start - Boot the VM
Load the metadata from the master storage domain metadata area.  Call the
VM.create() API.  Remove the metadata from the master storage domain.

VDSM will automatically purge old metadata from the master storage domain.  This
could be done any time a domain is: attached as master, deactivated, and
periodically.

How does this idea sound?  I am certain that it can be improved by those of you
with more experience and different viewpoints.  Thoughts and comments?

--
Adam Litke<a...@us.ibm.com>
IBM Linux Technology Center

_______________________________________________
vdsm-devel mailing list
vdsm-devel@lists.fedorahosted.org
https://fedorahosted.org/mailman/listinfo/vdsm-devel
_______________________________________________
vdsm-devel mailing list
vdsm-devel@lists.fedorahosted.org
https://fedorahosted.org/mailman/listinfo/vdsm-devel

Reply via email to