openstack team mailing list archive

[Anne Gentle <anne@xxxxxxxxxxxxx>]

I think it makes sense to have an openstack-api project with all the API
docs (specs and learning materials) gathered in one place. I think it's
preferable to have the API separated out from the code for several reasons -
ease of review, ease of check out, also for learning materials for the API
itself.

I'd envision these would go in it for starters:

Compute API (docbook, core + extensions)
Glance API (RST to docbook, core)
Keystone API (docbook, incubation, core + extensions)
Swift API (docbook, core)

Notes:
- Yep, Keystone moved their docbook out of the core code base due to the
"overhead" associated with a large-ish document ensconced with the code.
- Glance's API is documented in a single RST page. We have a simple RST to
docbook tool inhouse at Rackspace that lets me take updates and move them
into docbook.
- Just today I had a request to bring the Load Balancing API into
openstack-manuals for comments and review from
http://wiki.openstack.org/Atlas-LB, since our wiki doesn't enable comments.
I'm not sure what to do with nascent APIs for review that aren't yet in
incubation.

So these are some of my observations having worked with the API docs for a
while, to consider while seeking the ideal solution:
Incubation - how do we indicate an API is incubated?
Pre-incubation/review period - how could a team offer an API up for
community review and commenting?
Core - how do we indicate what is core and how to get extensions? At
Rackspace the Compute API team is working on a solution to getting
extensions and telling people how to use them once they're available.
Source - DocBook is the source for the two biggest API docs, Compute and
Object Storage, Keystone is a close third, and I can get DocBook out of
Glance. Do we need to set DocBook as the standard source?
Output - I'd also like to focus on not only API specs but also deliverables
that help people learn the APIs, such as the frameworks recently opensourced
by Mashery (example: http://developer.klout.com/iodocs) and Wordnik (
http://swagger.wordnik.com/). If we also deliver this type of web tool, we'd
also need JSON or XML as source files (many of which are already embedded
into the DocBook).

I'd like the best of both worlds - API specs and self-documenting APIs. I
think we can get there, and I think a separate API project with a core
review team moves us in that direction.

Thanks for the good discussion here.
Anne

* *
*Anne Gentle*
<http://www.facebook.com/conversationandcommunity>
my blog <http://justwriteclick.com/> | my
book<http://xmlpress.net/publications/conversation-community/>|
LinkedIn <http://www.linkedin.com/in/annegentle> |
Delicious<http://del.icio.us/annegentle>|
Twitter <http://twitter.com/annegentle>
On Mon, Aug 22, 2011 at 7:49 PM, Jan Drake <jan_drake@xxxxxxxxxxx> wrote:

> +1
>
>
>
>
> On Aug 22, 2011, at 5:06 PM, Jay Pipes <jaypipes@xxxxxxxxx> wrote:
>
> > ++
> >
> > On Mon, Aug 22, 2011 at 7:59 PM, Jorge Williams
> > <jorge.williams@xxxxxxxxxxxxx> wrote:
> >> Hi Vish,
> >> I don't have a problem moving the spec out of docs manuals and into
> another
> >> project even the nova repo.   But, I do have a number of issues with the
> >> approach that you're proposing. First, I think that fundamentally there
> >> should be a decoupling of the spec and the implementation.   If you have
> the
> >> spec generated from the code than essentially the spec is whatever the
> code
> >> does. It's very difficult to interoperate with specs that are generated
> this
> >> way as the specs tend to be very brittle and opaque (since you have to
> study
> >> the code). If you introduce a  bug in the code that bug filters it's way
> all
> >> the way to the spec (this was a big problem with SOAP and CORBA). It's
> >> difficult to detect errors because you cant validate. By keeping the
> >> implementation and the spec separate you can validate one against the
> other.
> >>
> >> Second, I don't think that the core OpenStack API should change with
> every
> >> OpenStack release. There are a number of efforts to provide multiple
> >> implementation of an existing OpenStack API.  We should encourage this,
> but
> >> it becomes difficult if the core spec is in constant flux.  Certainly
> you
> >> can use the extension mechanism to bring functionality out to market
> >> quickly, but the process of deciding what goes into the core should be
> more
> >> deliberate. Really good specs, shouldn't need to change very often,
> think
> >> HTTP, X11, SMTP, etc. We need to encourage clients to write support for
> our
> >> spec and we need to also encourage other implementors to write
> >> implementations for it. These efforts become very difficult if the spec
> is
> >> in constant flux.
> >> -jOrGe W.
> >> On Aug 22, 2011, at 5:43 PM, Vishvananda Ishaya wrote:
> >>
> >> Hey Everyone,
> >> We discussed at the Diablo design summit having API spec changes be
> proposed
> >> along with code changes and reviewed according to the merge process that
> we
> >> use for code.  This has been impossible up until now because the
> canonical
> >> spec has been in the openstack-manuals project.
> >> My suggestion is that we move the openstack-compute spec into the nova
> >> source tree.  During a six-month release we can propose changes to the
> spec
> >> by proposing along with the code that changes it.  In the final freeze
> for
> >> the release, we can increment the spec version number and copy the
> current
> >> version of the spec into openstack-manuals and that will be the locked
> down
> >> spec for that release.
> >> This means that openstack 1.1 will be the official spec for diablo, at
> which
> >> point we will start working on a new api (we can call it 1.2 but it
> might be
> >> best to use a temporary name like 'latest') during the essex release
> cycle,
> >> then at essex release we lock the spec down and it becomes the new
> version
> >> of the openstack api.
> >> Ultimately I would like the spec to be generated from the code, but as a
> >> first pass, we should at least be able to edit the future version of the
> >> spec as we make changes.  I've proposed the current version of the spec
> >> here:
> >> https://code.launchpad.net/~vishvananda/nova/add-api-docs/+merge/72506<https://code.launchpad.net/%7Evishvananda/nova/add-api-docs/+merge/72506>
> >> Are there any issues with this approach?
> >> Vish
> >>
> >> This email may include confidential information. If you received it in
> >> error, please delete it.
> >> _______________________________________________
> >> Mailing list: https://launchpad.net/~openstack
> >> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> >> Unsubscribe : https://launchpad.net/~openstack
> >> More help   : https://help.launchpad.net/ListHelp
> >>
> >>
> >
> > _______________________________________________
> > Mailing list: https://launchpad.net/~openstack
> > Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> > Unsubscribe : https://launchpad.net/~openstack
> > More help   : https://help.launchpad.net/ListHelp
>
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp
>