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  for the stable API and extracted some of the
> > > "TODO" points so we don't forget. Everyone can feel free to add more
> > > stuff.
> > >
> > >  http://ovirt.org/wiki/VDSM_Stable_API_Plan
> > >
> > > Rest of the comments inline
> > > ----- Original Message -----
> > > > From: "Adam Litke" <a...@us.ibm.com>
> > > > To: "Saggi Mizrahi" <smizr...@redhat.com>
> > > > Cc: "VDSM Project Development" <firstname.lastname@example.org>,
> > > > "Barak Azulay" <bazu...@redhat.com>, "Itamar
> > > > Heim" <ih...@redhat.com>, "Ayal Baron" <aba...@redhat.com>, "Anthony
> > > > Liguori" <aligu...@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).
Adam Litke <a...@us.ibm.com>
IBM Linux Technology Center
vdsm-devel mailing list