On 10/10/2014 02:05 AM, Christopher Yeoh wrote:
I agree with what you've written on the wiki page. I think our priority
needs to be to flesh out
so we have something to reference when reviewing specs. At the moment I
see that document as something anyone should be able to document a
project's API convention even if they conflict with another project for
the moment. Once we've got a fair amount of content we can start as a
Agreed that we should be fleshing out the above wiki page. How would you
like us to do that? Should we have an etherpad to discuss individual
topics? Having multiple people editing the wiki page offering commentary
seems a bit chaotic, and I think we would do well to have the Gerrit
review process in place to handle proposed guidelines and rules for
APIs. See below for specifics on this...
Speaking of the wiki page, I wrote it very matter-of-factly. As if
this is the way things are. They’re not. The wiki page is just a
starting point. If something was missed, add it. If something can be
improved, improve it. Let’s try to keep it simple though.
One problem with API WG members reviewing spec proposals that affect the
API is finding the specs in the first place across many different
I've said for a while now that I would love to have separate
repositories -- ala the Keystone API in the openstack/identity-api
repository -- that contains specifications for APIs in a single format
(APIBlueprint was suggested at one point, but Swagger 2.0 seems to me to
have more upside).
I also think it would be ideal to have an openstack/openstack-api repo
that would house guidelines and rules that this working group came up
with, along with examples of appropriate usage. This repo would function
very similar to the openstack/governance  repo that the TC uses to
flesh out proposals on community, release management, and governance
If people are OK with this idea, I will go ahead and create the repo and
add the wiki page content as the initial commit, then everyone can
simply submit patches to the document(s) using the normal Gerrit
process, and we can iterate on these things using the same tools as
I invite everyone who chimed in on the original thread  that
kicked this off to add themselves as a member committed to making
the OpenStack APIs better. I’ve Cc’d everyone who asked to be kept
in the loop.
I already see some cross project summit topics  on APIs. But
frankly, with the number of people committed to this topic, I’d
expect there to be more. I encourage everyone to submit more API
related sessions with better descriptions and goals about what you
want to achieve in those sessions.
Yea if there is enough content in the API guidelines then perhaps some
time can be spent on working on resolving any conflicts in the document
so projects know what direction to head in.
OpenStack-dev mailing list
OpenStack-dev mailing list