Andy, Dan, The other Openstack projects currently provide a WADL file in their documentation. However, unlike WS-*, to the best of my knowledge, with RestFul Web Services there's no official "schema" for documenting inputs and outputs for each operation. WADL files are typically used to this purpose, and there are code generators that will create client-side stubs from them.
Some RestFul Services do not have a WADL or any other kind of schema at all, and some of them, most notably Twitter (please forgive me if they released a formal spec recently :)), are pretty popular as well. Personally, I'm in favour of the "documenting by example" approach, but I definitely understand that we need to fulfil the expectations of the (hopefully) wide spectrum of developers writing client applications for Quantum. 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, 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<mailto: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:brocade....@lists.launchpad.net> [mailto:netstack-bounces+biermana<mailto:netstack-bounces%2Bbiermana>=brocade....@lists.launchpad.net<mailto:brocade....@lists.launchpad.net>] On Behalf Of Salvatore Orlando Sent: Wednesday, September 21, 2011 5:05 PM To: netstack@lists.launchpad.net<mailto: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<mailto: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<mailto:eu.citrix....@lists.launchpad.net> > [netstack- > bounces+salvatore.orlando=eu.citrix....@lists.launchpad.net<mailto:eu.citrix....@lists.launchpad.net>] > On Behalf > bounces+Of > Salvatore Orlando > [salvatore.orla...@eu.citrix.com<mailto:salvatore.orla...@eu.citrix.com>] > Sent: Thursday, September 15, 2011 6:09 PM > To: netstack@lists.launchpad.net<mailto: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<mailto:netstack@lists.launchpad.net> Unsubscribe : https://launchpad.net/~netstack More help : https://help.launchpad.net/ListHelp -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Dan Wendlandt Nicira Networks, Inc. www.nicira.com<http://www.nicira.com> | www.openvswitch.org<http://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
