Mailing List Archive: OpenStack: Dev

Nova API Specification

Index | Next | Previous | View Threaded

philip.day at hp

May 30, 2012, 6:33 AM

Post #1 of 3 (162 views)
Permalink

Nova API Specification

Hi Folks,

I was looking for the full definition of the API requests, and I'm a tad confused by what I find here:

http://api.openstack.org/

Specifically for Server Create there is both and "Server - Create" and "Server - Extended Create", although as far as I can see the "extended create" isn't actually an extension as such (the additional parameters are supported in the core servers module).

Also there seem to be a number of parameter values that aren't specified in either interface entry, such as:

min_count
max_count
networks
key_name

So is the API document intended to be:

- A formal specification of the Interface

- A set of examples (but if you want the details you need to read the code)

Are there plans to define the validation schematics of interface parameters ?

I have another specific question on what seems to be an inconsistency between the XML and JSON output of get server details:

The XML response defines the names of networks as values within the <addresses> section:

<addresses>
<network id="public">
<ip version="4" addr="67.23.10.132"/>

But in the JSON response it looks as if the network name is a structural element of the response:
"addresses": {
"public" : [
{
"version": 4,
"addr": "67.23.10.132"
},

i.e. depending on the value of the "label" field in the networks table of the nova database the structure of the JSON response seems to change (I may not be expressing that very well, my point is that "addresses" is fixed by the API definition, but "public" is defined per implementation ?

Is this a known issue ?

Cheers,
Phil

jorge.williams at rackspace

May 30, 2012, 11:46 AM

Post #2 of 3 (157 views)
Permalink

Re: Nova API Specification [In reply to]

On May 30, 2012, at 8:33 AM, Day, Phil wrote:

Hi Folks,

I was looking for the full definition of the API requests, and I’m a tad confused by what I find here:

http://api.openstack.org/

Specifically for Server Create there is both and “Server – Create” and “Server – Extended Create”, although as far as I can see the “extended create” isn’t actually an extension as such (the additional parameters are supported in the core servers module).

Also there seem to be a number of parameter values that aren’t specified in either interface entry, such as:

min_count
max_count
networks
key_name

So is the API document intended to be:

- A formal specification of the Interface
- A set of examples (but if you want the details you need to read the code)

You should also look at:

http://docs.openstack.org/api/

Are there plans to define the validation schematics of interface parameters ?

There are WADL and XML Schemas for the core here:

https://github.com/openstack/compute-api/blob/master/openstack-compute-api-2/src/os-compute-2.wadl

and here:

https://github.com/openstack/compute-api/tree/master/openstack-compute-api-2/src/xsd

nothing to validate the JSON...yet

I have another specific question on what seems to be an inconsistency between the XML and JSON output of get server details:

The XML response defines the names of networks as values within the <addresses> section:

<addresses>
<network id="public">
<ip version="4" addr="67.23.10.132"/>

But in the JSON response it looks as if the network name is a structural element of the response:
"addresses": {
"public" : [
{
"version": 4,
"addr": "67.23.10.132"
},

i.e. depending on the value of the “label” field in the networks table of the nova database the structure of the JSON response seems to change (I may not be expressing that very well, my point is that “addresses” is fixed by the API definition, but “public” is defined per implementation ?

Addresses is fixed in both the XML and JSON. public is implementation specific in both as well.

-jOrGe W.

anne at openstack

May 30, 2012, 4:53 PM

Post #3 of 3 (168 views)
Permalink

Re: Nova API Specification [In reply to]

Hi Phil -
An attempt at responses below, hopefully others can chime in where my
knowledge is limited. To answer an overarching (or is it underlying?)
question, the end goal is that the API descriptive specs are at
docs.openstack.org/api (even though some are named developer guides),
and the implementation in TryStack is documented at api.openstack.org.
Extensions are documented on api.openstack.org.

On Wed, May 30, 2012 at 8:33 AM, Day, Phil <philip.day [at] hp> wrote:
> Hi Folks,
>
> I was looking for the full definition of the API requests, and I’m a tad
> confused by what I find here:
>
> http://api.openstack.org/
>
> Specifically for Server Create there is both and “Server – Create” and
> “Server – Extended Create”, although as far as I can see the “extended
> create” isn’t actually an extension as such (the additional parameters are
> supported in the core servers module).
>
>

Extended Create is an extension as I understand it. When I query
TryStack I see {"updated": "2011-07-19T00:00:00+00:00", "name":
"Createserverext", "links": [], "namespace":
"https://docs.openstack.org/ext/createserverext/api/v1.1", "alias":
"os-create-server-ext", "description": "Extended support to the Create
Server v1.1 API"}, {"updated": "2011-08-08T00:00:00+00:00",

So to me that means the action servers is extended but because it uses
the same action, it seems a part of core (and min_count and max_count
are required aren't they?). Brian Waldon can probably explain better
than I can.

>
> Also there seem to be a number of parameter values that aren’t specified in
> either interface entry, such as:
>
> min_count
>
> max_count
>
> networks
>
> key_name
>

I logged this as a doc bug:
https://bugs.launchpad.net/openstack-manuals/+bug/1006654

>
> So is the API document intended to be:
>
>
>
> - A formal specification of the Interface
>
> - A set of examples (but if you want the details you need to read
> the code)
>

One of my goals going forward is crisper lines for docs about using
the APIs and docs describing the APIs. Users of the API should not
need to read Python code to use an OpenStack API. Thanks for your
observations.

Anne

_______________________________________________
Mailing list: https://launchpad.net/~openstack
Post to : openstack [at] lists
Unsubscribe : https://launchpad.net/~openstack
More help : https://help.launchpad.net/ListHelp

Index | Next | Previous | View Threaded

Interested in having your list archived? Contact Gossamer Threads