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). _______________________________________________ vdsm-devel mailing list vdsm-devel@lists.fedorahosted.org https://fedorahosted.org/mailman/listinfo/vdsm-devel
