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" <a...@us.ibm.com> > To: "Dan Kenigsberg" <dan...@redhat.com> > Cc: "Saggi Mizrahi" <smizr...@redhat.com>, "VDSM Project Development" > <vdsm-devel@lists.fedorahosted.org>, "Daniel > Veillard" <veill...@redhat.com>, "Anthony Liguori" <aligu...@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" <a...@us.ibm.com> > > > > > To: "Saggi Mizrahi" <smizr...@redhat.com> > > > > > Cc: "VDSM Project Development" > > > > > <vdsm-devel@lists.fedorahosted.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). > > +1 > > -- > Adam Litke <a...@us.ibm.com> > IBM Linux Technology Center > > _______________________________________________ vdsm-devel mailing list vdsm-devel@lists.fedorahosted.org https://fedorahosted.org/mailman/listinfo/vdsm-devel
