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).
+1 -- Adam Litke <a...@us.ibm.com> IBM Linux Technology Center _______________________________________________ vdsm-devel mailing list email@example.com https://fedorahosted.org/mailman/listinfo/vdsm-devel