[Ovirt-devel] OVirt public API

[Daniel P. Berrange]

On Wed, Jul 16, 2008 at 04:07:19PM -0400, Michael DeHaan wrote:
> David Lutterkort wrote:
> >Here is my current thinking around a public API for OVirt. The basic
> >idea is that that API will expose all operations that are available
> >through the WUI, with small adaptations to the fact that it's an API,
> >and not an interactive interface.
> >
> >In particular, the API will (eventually) support the following:
> >
> >  * Lifecycle control for virtual machines
> >    (start/stop/suspend/resume/migrate)
> >
> >  * Management of the various pools, i.e. host, storage and VM pools
> >
> >  * Querying of information about the above; I'd explicitly exclude
> >    performance data from this 'information' - I think that should be
> >    communicated by different means (e.g., collectd)
> >
> >Architecturally, the API will be a remote API over HTTP, using a RESTful
> >style; in a nutshell, that means that clients make calls through HTTP
> >requests, with arguments and results suitably encoded - for GET
> >requests, that simply means ordinary request params, for POST, it's TBD
> >which possible ways to serialize data is preferrable. Obvious candidates
> >are XML, YAML, and JSON; right now, I am leaning towards
> >XML. Stylistically, REST uses URL's to represent objects (or 'nouns')
> >and different HTTP methods to retrieve and/or change those objects
> >('verbs') You can think of the HTTP methods GET, POST, PUT, DELETE as
> >analogous to the SQL actions select, insert, update, and delete,
> >respectively. Or the show/create/update/delete methods in Rails
> >controllers.
> >
> >Besides being lightweight, a RESTful API is also very attractive because
> >of the support for it in Rails 2 (ActionController::Resources on the
> >server side, and ActiveResource for clients) That support takes away a
> >lot of the headaches around serialization of objects, routing etc.
> >  
> 
> I would make an argument for XMLRPC/SSL based on that a lot of our 
> management applications already have XMLRPC API's (such as 
> Spacewalk/Cobbler/etc), and that serialization and more remote faults 
> are supported. 

That's rubbish - REST is just as expressive as XMLRPC in terms of data
serialization and fault reporting - in fact its more expressive, since
it is not tied into the XMLRPC format.  This examples shows one way in
which a fault response used in XMLRPC can trivially be mapped into a 
REST style API.

http://www.flickr.com/services/api/response.rest.html
http://www.flickr.com/services/api/response.xmlrpc.html

You don't even need to use the same serialization format for errors vs 
normal responses since you can distinguish a fault based on the HTTP 
return code.

Since REST is just plain HTTP, the expressiveness is entirely at your
control when defining the data format for your HTTP responses. You get
to choose whether to provide an unstructured text blob response, or a
structured XML document - whichever best suits the needs of the API.

Daniel
-- 
|: Red Hat, Engineering, London   -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 :|