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:[email protected]]
Sent: Thursday, September 22, 2011 10:36 AM
To: Andy Bierman
Cc: Salvatore Orlando; [email protected]
Subject: Re: [Netstack] API documentation ready for review
On Thu, Sep 22, 2011 at 10:00 AM, Andy Bierman
<[email protected]<mailto:[email protected]>> 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:
[email protected]<mailto:[email protected]>
[mailto:netstack-bounces+biermana<mailto:netstack-bounces%2Bbiermana>[email protected]<mailto:[email protected]>]
On Behalf Of Salvatore Orlando
Sent: Wednesday, September 21, 2011 5:05 PM
To: [email protected]<mailto:[email protected]>
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;
> [email protected]<mailto:[email protected]>
> 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-
> [email protected]<mailto:[email protected]>
> [netstack-
> [email protected]<mailto:[email protected]>]
> On Behalf
> bounces+Of
> Salvatore Orlando
> [[email protected]<mailto:[email protected]>]
> Sent: Thursday, September 15, 2011 6:09 PM
> To: [email protected]<mailto:[email protected]>
> 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 : [email protected]<mailto:[email protected]>
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 : [email protected]
Unsubscribe : https://launchpad.net/~netstack
More help : https://help.launchpad.net/ListHelp
