[libvirt] [RFC] API vs XML

[Daniel P. Berrange]

On Fri, May 16, 2008 at 01:26:07AM +0200, Stefan de Konink wrote:
> But why are the XML tree manipulating features not incorporated into the
> API? Slightly more 'semantics based' than Attach/Detach Device. Allowing
> to specify the information that is going into the XML.
> 
> So for example:
> domainptr = virDomainDefine(name)
> virDomainSetName(domainptr, name)
> virDomainSetBootloader(domainptr, path)
> virDomainSetOS(domainptr, type)
> virDomainSetMemory(domainptr, amount, live)
> virDomainSetVCPU(domainptr, amount, live)
> virDomainAttachDisk(domainptr, type, sourceptr, targetptr, live)
> virDomainDetachDevice(domainptr, deviceptr, live)
> 
> I know there are people that love XML here, but can someone give a
> reasonable statement why not to support the above? (More clean, less
> parsing)

Less easily extendable, while maintaining ABI compatability. For nearly
every functional aspect of the XML, we have had to add new attributes
or elements as we've learned more about usage scenario, and ported to
other hypervisors. If we exposed everything via the API we'd be adding
new APIs, deprecating old APIs. Take your 'virDomainAttachDisk' example,
we just lsat week added a 'bus' attribute to disk, so we'd now need to
add a virDomainAttachDiskWithBus method. Then we need to also provide
the disk format type (qcow, vmdk, raw, etc), so we'll need another API
virDomainAttachDiskWithBusFormat. This is non scalable. Other alternatives
are to create a big pile of structs for all the data, but then we need to
be able to add new struct elements, so we'll be passing around piles of
flags, or sizeof() on the structs.  All this stuff has to be replicated
in all the language bindings for the API (Perl, Python, Java, Ruby, OCaml,
etc).

Maintaining stable ABIs is very hard work, and even for our existing APIs
we have made mistakes in the past which we have to live with - eg we now
have 3 virConnectOpen() methods. The migration ABI for the remote protocol
was very carefully planed & designed to be extendable, but we discovered
we couldn't quite manage to make it work for QEMU.

Maintaining stable XML format is also pretty non-trivial, and we've made 
mistakes here too, but it is easier to add attributes and elements to the 
document describing a VM without risking the ABI compatability. Most of
our mistakes have been todo with poor choice of naming for concepts and
some illogical structure in areas. 

Dan.
-- 
|: Red Hat, Engineering, Boston   -o-   http://people.redhat.com/berrange/ :|
|: http://libvirt.org  -o-  http://virt-manager.org  -o-  http://ovirt.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: GnuPG: 7D3B9505  -o-  F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|