Hi, I read the API spec (again) and I have the same comment as last time.
There are no normative definitions for any output from Quantum. IMO, a RelaxNG pattern is needed for every 'XML blob' that is defined by example. An application needs to know the XML or JSON structure to expect. It needs to know the list of enum strings to expect. How can I write a 'switch statement' in my application code for port-state when none of the enums are defined anywhere? If a formal spec is too hard, then how about specifying the data type for every field? (list all enums, and the rest are unconstrained strings?) If the enums are actually unconstrained strings, then programming to this API is going to be a 1-off for every plugin. That seems to be the plan so far. If so, the spec should say in bold letters "All values returned are implementation-dependent." Andy -----Original Message----- From: netstack-bounces+biermana=brocade....@lists.launchpad.net [mailto:netstack-bounces+biermana=brocade....@lists.launchpad.net] On Behalf Of Salvatore Orlando Sent: Wednesday, September 21, 2011 5:05 PM To: netstack@lists.launchpad.net Subject: Re: [Netstack] API documentation ready for review And the documentation got updated again! This time we removed references to Keystone and reworked the Authentication section, trying to conveying the message that at the moment Quantum is not integrated with any authentication mechanism, but deployers are free to use their favourite mechanisms by appropriately configuring the Quantum pipeline. Also, Rajaram's contribute on API extensions has been integrated into the attached API guide. Salvatore > -----Original Message----- > From: Salvatore Orlando > Sent: 20 September 2011 00:56 > To: Salvatore Orlando; netstack@lists.launchpad.net > Subject: RE: API documentation ready for review > > Hello again, > > following your precious feedback, here's an updated version of the API > documentation. > Special thanks to Dan for his detailed review and for contributing the > section on Async behaviour. > > The branch on launchpad: lp:~salvatore-orlando/quantum/quantum-api-doc > has been updated as well. > > Salvatore > ________________________________________ > From: netstack- > bounces+salvatore.orlando=eu.citrix....@lists.launchpad.net [netstack- > bounces+salvatore.orlando=eu.citrix....@lists.launchpad.net] On Behalf > bounces+Of > Salvatore Orlando [salvatore.orla...@eu.citrix.com] > Sent: Thursday, September 15, 2011 6:09 PM > To: netstack@lists.launchpad.net > Subject: [Netstack] API documentation ready for review > > Hi Netstackers, > > The documentation for the Quantum API is now ready for review: > https://code.launchpad.net/~salvatore-orlando/quantum/quantum-api- > doc/+merge/75588 > Unfortunately there are no unit tests or compilers for documentation; > so I'm pretty sure there are several things to be fixed (page breaks for a > starter). > I would be therefore more than happy if you could have a look at it. > > In order to make things a bit easier for you, I'm attaching the PDF > version of the document, so you won't have to go through the docbook XML! > > Cheers, > Salvatore -- Mailing list: https://launchpad.net/~netstack Post to : netstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~netstack More help : https://help.launchpad.net/ListHelp
