[Ovirt-devel] OVirt public API

[Michael DeHaan]

Daniel P. Berrange wrote:
> 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.
>   

Yes, being able to talk in Esperanto to someone talking Finnish is 
expressive, and being able to make up your own language is more 
expressive than that. Yet this is software, and those things are bad :)

This fault info as is defined by the Flickr return codes not REST as a 
specification --- REST allows basically any transport and has almost no 
conventions. It is a nice hack for mashups, but as a standard or even a 
well codified specification, it's not one. The data format is not 
defined. It's expressive because they made it expressive, sure, but at 
what cost to the caller? Why not use the libraries that are available to 
make this stuff simple?

Most languages (pseudocodey) have XMLRPC libraries that work out of the 
box and the caller doesn't have to care what your transfer format is or 
how you express your faults. You don't have to ship a client-side flickr 
library even, there's no need for one. However, for REST, lots of people 
/did/ have to write these to make it all glue together appropriately.

It would be nice if all languages had something like this for REST like 
they do for XMLRPC, but this is not possible as the fault system and the 
interchange formats are not defined

import restlibrary_from_standard_distribution as restfoo
connection = restfoo.connect("http://blah")
try:
connection.foo.bar(1,2,3,"baz")
except:
something else

With XMLRPC, that is possible, as that is what it was designed to do.




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