Open Stack

> -----Original Message-----
> From: Jay Pipes [mailto:jaypipes at gmail.com]
> Sent: Wednesday, September 24, 2014 1:09 AM
> To: openstack-dev at lists.openstack.org
> Subject: Re: [openstack-dev] [Nova] Some ideas for micro-version implementation
> 
> > (1) Input/Output attribute names
> > (1.1) These names should be snake_case.
> >    eg: imageRef -> image_ref, flavorRef -> flavor_ref, hostId -> host_id
> 
> Sure, agreed.
> 
> > (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
> > (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
> > (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)
> 
> Frankly, API extensions are a sore on the lip of OpenStack's smile.
> 
> They add needless complexity to the API and I believe a discoverable API
> with its resources micro-versioned with schema objects means that API
> extensions should just go the way of the Dodo.

I agree with removing extension names from attribute names as I said on the
other mail. Extension names seems to make attribute name long and complex.

However, the extension *internal* mechanism of v2.1/v3 API is good for me
because we can separate each extension implementation from core part of Nova,
make the code clean and choose necessary extensions as you like. Maybe this
is off-topic because we are discussing external REST API design.


> > (1.5) The length of the first attribute depth should be one.
> >    eg: "create a server" API with scheduler hints
> >      -- v2 API input attribute sample ---------------------------------------
> >        {
> >            "server": {
> >                "imageRef": "e5468cc9-3e91-4449-8c4f-e4203c71e365",
> >                [..]
> >            },
> >            "OS-SCH-HNT:scheduler_hints": {
> >                "same_host": "5a3dec46-a6e1-4c4d-93c0-8543f5ffe196"
> >            }
> >        }
> >      -- v3 API input attribute sample ---------------------------------------
> >        {
> >            "server": {
> >                "image_ref": "e5468cc9-3e91-4449-8c4f-e4203c71e365",
> >                [..]
> >                "os-scheduler-hints:scheduler_hints": {
> >                    "same_host": "5a3dec46-a6e1-4c4d-93c0-8543f5ffe196"
> >                }
> >            }
> >        }
> 
> -1. What is the point of the containing "server" attribute in the outer
> dict? Why have it at all?
>
> Each resource in the REST API should have the same structure: all
> attributes should be top-level, and a special "_links" attribute should
> be used for the collection of named hyperlinks using the HAL format [1].
> Simple, consistent, and discoverable. No need for the top-level "server"
> key in the outer dict. Frankly, that is a vestigial tail from the days
> of XML that we should saw off with a dull blade.
> 
> [1] http://stateless.co/hal_specification.html. An alternative might be
> the use of JSON-LD for link structuring. See
> https://www.mnot.net/blog/2011/11/25/linking_in_json for a good
> discussion of this topic.

Interesting suggestion, thanks Jay!
I'm not sure HAL is the best at this time, but all flat attributes are very
simple and easy anyway.

> > (2) Resource names
> > (2.1) Resource names should consist of hyphens and low chars.
> 
> ++

thanks, but this seems against Pecan/WSME restriction.
On Pecan/WSME, I think we can specify snake_case only as resource names and attributes names.

> >    eg: /os-instance_usage_audit_log -> /os-instance-usage-audit-log
> > (2.2) Resource names should contain the prefix "os-" if the extension is not core.
> >    eg: /servers/diagnostics -> /servers/os-server-diagnostics
> >        /os-flavor-access -> /flavor-access (flavor-access extension became core)
> > (2.3) Action names should be snake_case.
> >    eg: os-getConsoleOutput -> get_console_output
> >        addTenantAccess -> add_tenant_access, removeTenantAccess -> remove_tenant_access
> 
> No extensions, please.

This extensions you said mean server actions?
Current Nova API router is routing server actions based on both API URL and the attributes,
and that seems a little complex for me.

Thanks
Ken'ichi Ohmichi