On Thu, Sep 22, 2011 at 2:15 PM, Salvatore Orlando < salvatore.orla...@eu.citrix.com> wrote:
> ** ** > > For this reason I believe that Quantum API needs at least a WADL file. I’m > voting for WADL in order to be consistent with the other Openstack projects, > > That seems like the right call if that is what the other projects have standardized on. Want to file an Essex BP? (no session needed, but a BP will help us track this and assign it to a milestone). dan > but I’m not against any other formal specification, be it XSD, Relax-NG, > Schematron, or JSON schema. **** > > I apologise if no formal description has been provided for Quantum API 1.0; > a formal description will be provided soon. I hope we can keep this thread > open, as client applications are IMHO the most important resource for the > success of the Quantum service!**** > > ** ** > > Thanks for reviewing the documentation,**** > > Salvatore**** > > ** ** > > ** ** > > *From:* Andy Bierman [mailto:bierm...@brocade.com] > *Sent:* 22 September 2011 19:33 > *To:* Dan Wendlandt > > *Cc:* Salvatore Orlando; netstack@lists.launchpad.net > *Subject:* RE: [Netstack] API documentation ready for review**** > > ** ** > > Hi,**** > > ** ** > > OK – I guess it is clear enough that the only allowed strings for > port-state > are ACTIVE and DOWN, and hopefully the behavior for ACTIVE or DOWN > is roughly the same on all implementations.**** > > ** ** > > It’s more than a first step. It is very complete, except for the formal > schema..**** > > Our application developers actually use them in their tools.**** > > They will have to be generated from the text, if not included.**** > > Since JSON doesn’t have attributes (good!), a separate grammar for XML is > needed.**** > > ** ** > > (Here is a start, hope it’s right)**** > > **** > > Port = > element port {**** > > attribute id { text }, > attribute state { “ACTIVE” | “DOWN” }, > element attachment { > attribute id { test } > }? > }**** > > **** > > Ports = > element ports { Port* }**** > > ** ** > > Network = > element network { > attribute id { text }, > attribute name { text }, > Ports? > }**** > > ** ** > > ** ** > > Andy**** > > ** ** > > **** > > *From:* Dan Wendlandt [mailto:d...@nicira.com] > *Sent:* Thursday, September 22, 2011 10:36 AM > *To:* Andy Bierman > *Cc:* Salvatore Orlando; netstack@lists.launchpad.net > *Subject:* Re: [Netstack] API documentation ready for review**** > > ** ** > > ** ** > > On Thu, Sep 22, 2011 at 10:00 AM, Andy Bierman <bierm...@brocade.com> > wrote:**** > > 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."**** > > ** ** > > Hi Andy,**** > > ** ** > > Thanks for reviewing the doc. It is definitely still a work in progress, > but I think it is a great first step. **** > > ** ** > > Can you be more specific about the enums that you are having trouble with? > The only enum that comes to my mind right away from the "core" API is port > state, and searching through the doc finds many mentions of the fact that > "ACTIVE" and "DOWN" are the two valid values for this field: **** > > ** ** > > - Quantum API allows for controlling the administrative state of the port, > which can be either 'DOWN' or 'ACTIVE'.**** > > - A port has an administrative state which is either 'DOWN' or 'ACTIVE'.** > ** > > - Currently Quantum recognizes two port states: DOWN and ACTIVE.**** > > ** ** > > It looks like the call to dump supported versions also has "CURRENT" and > "FUTURE", which probably could be defined explicitly, but that is a > fairly peripheral call. **** > > ** ** > > Or am I misunderstanding what you are meaning by saying "enum"? **** > > ** ** > > None of the values returned by a plugin should be plugin-specific unless > part of an extension that itself is plugin-specific. If there's something > that implies otherwise, we should try and clarify that in the text in the > document. **** > > ** ** > > I like the idea of having a more formal specification of the schema (I've > used JSON schema in the past, though it has its quirks). Ultimately, this > is probably an issue we should raise with the larger OpenStack API > community, as we would ideally all agree on common approach. I don't see > any type of formal spec even for "core" OpenStack projects like compute yet > ( > http://docs.openstack.org/trunk/openstack-compute/developer/openstack-compute-api-1.1/content/index.html), > but perhaps someone more knowledgable in that area can chime in. I > definitely think a blueprint to more formally define the spec would be > welcomed.**** > > ** ** > > Dan**** > > ** ** > > ** ** > > **** > > > > > 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**** > > > > **** > > ** ** > > -- > ~~~~~~~~~~~~~~~~~~~~~~~~~~~ > Dan Wendlandt > Nicira Networks, Inc. > www.nicira.com | www.openvswitch.org > Sr. Product Manager > cell: 650-906-2650 > ~~~~~~~~~~~~~~~~~~~~~~~~~~~**** > -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Dan Wendlandt Nicira Networks, Inc. www.nicira.com | www.openvswitch.org Sr. Product Manager cell: 650-906-2650 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- Mailing list: https://launchpad.net/~netstack Post to : netstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~netstack More help : https://help.launchpad.net/ListHelp
