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
~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- 
Mailing list: https://launchpad.net/~netstack
Post to     : netstack@lists.launchpad.net
Unsubscribe : https://launchpad.net/~netstack
More help   : https://help.launchpad.net/ListHelp

Reply via email to