Open Stack

Hi Jay and the dev-list
Thanks for circling back on this Jay, I had spoken to Ian at length on
IRC before the Summit and forgot to post to the list as well.

On Tue, Nov 6, 2012 at 5:06 PM, Jay Pipes <jaypipes at gmail.com> wrote:
> 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...

So, api.openstack.org was originally an experiment to get all the
extensions in one place, but I do believe it has met that objective
and now it's time to stop confusing people with "what's the difference
between docs.openstack.org/api and api.openstack.org? So that's the
first step - get a more descriptive landing page on api.openstack.org
rather than a long list of calls.

> 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

We do have a new-ish CLI guide [1] for all the OpenStack CLIs linked
from the docs landing page. So I agree here and the content is shared
with the Compute Admin Manual too.

> 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

I always like for URLs to self-describe what's going on. Not sure if
we have to get this fine a point on it but I'll certainly take it into
consideration for the api site work. The work so far is:

-Track bugs against api.openstack.org at a new Launchpad project,
openstack-api-site.
-Change CI Infrastructure builds to build from a new
openstack/api-site repo on GitHub.

What'll happen next is to change the landing page at api.openstack.org
so the long listing is a sub-page, api.openstack.org/api-ref.html.
Then I'll also redirect from docs.openstack.org/api to
api.openstack.org. I think the landing page is going to be:

API Reference
API Specs
SDKs

Then when you click through to API Reference we can start to build out
all these examples and finish out the blueprint to bring in all the
tested Compute API samples.

I don't know if we have to do /python/ /http/ /php/ /java/ sub
directories but that might be fine, what do others think of Jay's
examples?

I'd also like to get much more practical documentation than spec
documentation. Where do all these code samples come from? The amount
of work to integrate hundreds of new Compute code samples is a long
list, we'll just piece through it, but do other APIs have that many
tested examples (hundreds)? Let me know how to find 'em and I'll find
a way to integrate them and be smart about it. I haven't found many
people willing to do the tedious API doc work so if you're even
thinking of helping out, please do so!

Thanks for keeping on it you all!
Anne

> We could further have examples for any other language bindings follow
> the same kind of sitemap structure.
>
> Thoughts?
> -jay

[1] http://docs.openstack.org/cli/quick-start/content/index.html