On Mon, 22 Sep 2014 09:47:50 -0500 Anne Gentle <a...@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 _______________________________________________ OpenStack-dev mailing list OpenStackemail@example.com http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev