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 <a...@us.ibm.com> IBM Linux Technology Center _______________________________________________ vdsm-devel mailing list vdsm-devel@lists.fedorahosted.org https://fedorahosted.org/mailman/listinfo/vdsm-devel