I tired to sum everything in the wiki page [1] Please review the page and see if there is something I missed or that you don't agree with.
----- Original Message -----
From: "Adam Litke" agl@us.ibm.com To: "Dan Kenigsberg" danken@redhat.com Cc: "Saggi Mizrahi" smizrahi@redhat.com, "VDSM Project Development" vdsm-devel@lists.fedorahosted.org, "Daniel Veillard" veillard@redhat.com, "Anthony Liguori" aliguori@redhat.com Sent: Thursday, June 21, 2012 10:41:36 AM Subject: Re: [vdsm] [virt-node] RFC: API Supportability
On Thu, Jun 21, 2012 at 01:20:40PM +0300, Dan Kenigsberg wrote:
On Wed, Jun 20, 2012 at 10:42:16AM -0500, Adam Litke wrote:
On Tue, Jun 19, 2012 at 10:17:28AM -0400, Saggi Mizrahi wrote:
I've opened a wiki page [1] for the stable API and extracted some of the "TODO" points so we don't forget. Everyone can feel free to add more stuff.
[1] http://ovirt.org/wiki/VDSM_Stable_API_Plan
Rest of the comments inline ----- Original Message -----
From: "Adam Litke" agl@us.ibm.com To: "Saggi Mizrahi" smizrahi@redhat.com Cc: "VDSM Project Development" vdsm-devel@lists.fedorahosted.org, "Barak Azulay" bazulay@redhat.com, "Itamar Heim" iheim@redhat.com, "Ayal Baron" abaron@redhat.com, "Anthony Liguori" aliguori@redhat.com Sent: Monday, June 18, 2012 12:23:10 PM Subject: Re: [virt-node] RFC: API Supportability
On Mon, Jun 18, 2012 at 11:02:25AM -0400, Saggi Mizrahi wrote:
The first thing we need to decide is API supportabiliy. I'll list the questions that need to be answered. The decision made here will have great effect on transport selection (espscially API change process and versioning) so try and think about this without going to specfic technicalities (eg. "X can't be done on REST").
Thanks for sending this out. I will take a crack at these questions...
I would like to pose an additional question to be answered:
- Should API parameter and return value constraints be
formally defined? If so, how?
Think of this as defining an API schema. For example: When creating a VM, which parameters are required/optional? What are the valid formats for specifying a VM disk? What are all of the possible task states?
Has to be part of response to the call that retrieves the state. This will allow us to change the states in a BC manner.
I am not sure I agree. I think it should be a part of the schema but not transmitted along with each API response involving a task. This would increase traffic and make responses unnecessarily verbose.
Is there a maximum length for the storage domain description?
I totally agree, how depends on the transport of choice but in any case I think the definition should be done in a declarative manner (XML\JSON) using concrete types (important for binding with C\Java) and have some *code to enforce* that the input is correct. This will prevent clients from not adhering to the schema exploiting python's relative lax approach to types. We already had issues with the engine wrongly sending numbers as strings and having this break internally because of some change in the python code made it not handle the conversion very well.
Our schema should fully define a set of simple types and complex types. Each defined simple type will have an internal validation function to verify conformity of a given input. Complex types consist of nested lists and dicts of simple types. They are validated first by validating members as simple types and then checking for missing and/or extra data.
When designing a dependable API, we should not desert our agility. ovirt-Engine has enjoyed the possibility of saying "hey, we want another field reported in getVdsStats" and presto, here it was. Complex types should be easily extendible (with a proper update of the API minor version, or a capabilities set).
+1
-- Adam Litke agl@us.ibm.com IBM Linux Technology Center