Open Stack

cc'ing Anne and Everett...

On 10/01/2012 10:44 AM, Ian Wells wrote:
> So I was helping a guy working on some Python client code, and I told him to
> look at the Python Openstack API for all his interface needs.  One
> confusing conversation later, I realised it's actually not at all as
> simple as that.

LOL, true that.

> The obvious place one might look for programming Nova via Python is
> the document on http://docs.openstack.org/api/ temptingly named
> 'Programming Openstack Compute API with Shell and Python'.  However,
> this makes no significant mention of Python, and actually not many
> mentions of the 'nova' command, focussing on curl as its command of
> choice.  I really don't think we should be recommending curl (or even
> web calls) as the primary interface for Python developers.

Indeed. Not that curl is bad or anything, but the examples, with their
use of the X-Auth-Token stuff and multiple calls to first Keystone and
then the Nova API endpoint, are confusing if you just want to either:

a) Understand the HTTP API calls and parameters
b) Want to use the Python bindings

I've been thinking that it might be useful to structure the API doc site
like so:

api.openstack.org/http => Would contain the sample request and responses
for all HTTP API calls for the different endpoints.

Underneath this would be:

api.openstack.org/http/compute
api.openstack.org/http/identity
etc...

api.openstack.org/python => Would be a place for examples of using the
Python bindings API exposed by python-*client packages. Would NOT be a
place for examples of using the CLI tools, though... that documentation
would/should live in the administrator's guide IMHO

So, for instance, api.openstack.org/python/compute would show examples
like this:

from novaclient.v1_1 import client
c = client.Client(USER, PASS, TENANT, AUTH_URL, service_type="compute")

for s in c.servers.find(host="myhost"):
    print s.id, s.name

But not examples like this:

$> nova list --host=myhost

We could further have examples for any other language bindings follow
the same kind of sitemap structure.

Thoughts?
-jay