Open Stack

On Mon, 22 Sep 2014 09:47:50 -0500
Anne Gentle <anne at openstack.org> wrote:
> >
> > (1) Input/Output attribute names
> > (1.1) These names should be snake_case.
> >   eg: imageRef -> image_ref, flavorRef -> flavor_ref, hostId ->
> > host_id (1.2) These names should contain extension names if they
> > are provided in case of some extension loading.
> >   eg: security_groups -> os-security-groups:security_groups
> >       config_drive -> os-config-drive:config_drive
> >
> 
> Do you mean that the os- prefix should be dropped? Or that it should
> be maintained and added as needed?


Originally (I think) the os- prefix was added to avoid potential
name clashes between extensions. Presumably out of tree extensions
too as in-tree ones would be picked up pretty quickly. For a while now
I've been thinking that perhaps we should just drop the os- prefix.
We're trying to discourage optional extensions anyway and I suspect that
the pain of maintaining consistency with os- prefixes is not worth the
benefit.

Where if someone wants to maintain an out of tree plugin they
can bear the burden of avoiding name clashes. This would make it much
easier for both us (nearly no code changes required) and users (no app
changes) when we move some functionality into (or out of) core.

> > (1.3) Extension names should consist of hyphens and low chars.
> >   eg: OS-EXT-AZ:availability_zone ->
> > os-extended-availability-zone:availability_zone
> >       OS-EXT-STS:task_state -> os-extended-status:task_state
> >
> 
> Yes, I don't like the shoutyness of the ALL CAPS.

+1! No to ALL CAPS and contractions or disemvowling of words in order
to save a few bytes.

> > (1.4) Extension names should contain the prefix "os-" if the
> > extension is not core.
> >   eg: rxtx_factor -> os-flavor-rxtx:rxtx_factor
> >       os-flavor-access:is_public -> flavor-access:is_public
> > (flavor-access extension became core)
> >
> 
> Do we have a list of "core" yet?

We do sort of have a candidate listed hard coded (its a pretty small
list):

API_V3_CORE_EXTENSIONS = set(['consoles',
                              'extensions',
                              'flavor-access',
                              'flavor-extra-specs',
                              'flavor-manage',
                              'flavors',
                              'ips',
                              'os-keypairs',
                              'server-metadata',
                              'servers',
                              'versions'])

> 
> > (3) Status code
> > (3.1) Return 201(Created) if a resource creation/updating finishes
> > before returning a response.
> >   eg: "create a keypair" API: 200 -> 201
> >       "create an agent" API: 200 -> 201
> >       "create an aggregate" API: 200 -> 201
> >
> 
> Do you mean a 200 becomes a 201? That's a huge doc impact and SDK
> impact, is it worthwhile? If we do this change, the sooner the
> better, right?

Ideally I think we'd want to do it when breaking a specific part of the
API anyway (for say some new feature). Otherwise its something I think
we should bring up on a case by case with users and operators. Trade
off between returning misleading status codes versus requiring
application side changes (potentially, some may just look for 2xx
anyway).

> >
> >
> The TC had an action item a while back (a few months) to start an API
> style guide. This seems like a good start. Once the questions are
> discussed I'll get a draft going on the wiki.

So back during the Juno design summit at the cross project API
consistency session we talked about putting together a wiki page with
guidelines for all OpenStack projects. But I think everyone got busy so
not much at all happened. I've had a bit of time recently and tried to
pull together info from the session as well as some other sources and
the start of it is here:

https://wiki.openstack.org/wiki/Governance/Proposed/APIGuidelines

So perhaps we could merge what is above into this wiki?
It is however still rather Nova specific and we need input from
other projects (I'll send out another email specifically about this). 

Chris