[openstack-dev] [all] Proposal for having a service type registry and curated OpenStack REST API

Monty Taylor mordred at inaugust.com
Mon Feb 8 16:04:35 UTC 2016

On 02/08/2016 06:16 AM, Sean Dague wrote:
> On 02/07/2016 08:13 PM, Monty Taylor wrote:
>> On 02/07/2016 07:30 AM, Jay Pipes wrote:
>>> On 02/04/2016 06:38 AM, Sean Dague wrote:
>>>> What options do we have?
>>> <snip>
>>>> 2) Have a registry of "common" names.
>>>> Upside, we can safely use common names everywhere and not fear collision
>>>> down the road.
>>>> Downside, yet another contention point.
>>>> A registry would clearly be under TC administration, though all the
>>>> heavy lifting might be handed over to the API working group. I still
>>>> imagine collision around some areas might be contentious.
>>> The above is my choice. I'd also like to point out that I'm only talking
>>> about the *service* projects here -- i.e. the things that expose a REST
>>> API.
>> yes
>>> I don't care about a naming registry for non-service projects because
>>> they do not expose a public user-facing API that needs to be curated and
>>> protected.
>> yes
>>> I would further suggest using the openstack/governance repo's
>>> projects.yaml file for this registry. This is already under the TC's
>>> administration and the API WG could be asked to work closely with the TC
>>> to make recommendations on naming for all type:service projects in the
>>> file. We should add a service:$type tag to the projects.yaml file and
>>> that would serve as the registry for REST API services.
>>> We would need to institute this system by first tackling the current
>>> areas of REST API functional overlap:
>>> * Ceilometer and Monasca are both type:service projects that are both
>>> performing telemetry functionality in their REST APIs. The API WG should
>>> work with both communities to come up with a 6-12 month plan for
>>> creating a *single* OpenStack Telemetry REST API that both communities
>>> would be able to implement separately as they see fit.
>>> * All APIs that the OpenStack Compute API currently proxies to other
>>> service endpoints need to have a formal sunsetting plan. This includes:
>>>    - servers/{server_id}/os-interface (port interfaces)
>>>    - images/
>>>    - images/{image_id}/metadata
>>>    - os-assisted-volume-snapshots/
>>>    - servers/{server_id}/os-bare-metal-nodes/ (BTW, why is this a
>>> sub-resource of /servers again?)
>>>    - os-fixed-ips/
>>>    - os-floating-ip-dns/
>>>    - os-floating-ip-pools/
>>>    - os-floating-ips/
>>>    - os-floating-ips-bulk/
>>>    - os-networks/
>>>    - os-security-groups/
>>>    - os-security-group-rules/
>>>    - os-security-group-default-rules/
>>>    - os-tenant-networks/
>>>    - os-volumes/
>>>    - os-snapshots/
>>> * All those services that have overlapping top-level resources must have
>>> a plan to either:
>>>    - align/consolidate the top-level resource if it makes sense
>>>    - rename the top-level resource to be more specific if needed, or
>>>    - place the top-level resource as a sub-resource on a top-level
>>> resource that is unique in the full OpenStack REST API set of top-level
>>> resources
>> Yes please god yes oh yes a million times yes. I've never agreed with
>> you as much as this since the JSON/XML glory of the Cactus summit.
>> I know shade is not the OpenStack SDK - but as a library that has a top
>> level "OpenStackCloud" object that has methods like "list_servers" and
>> "list_images" - things that overlap in conceptual name but do not
>> present the same semantics quickly become difficult. I believe Jay's
>> proposal above will help to make the situation much more saner.
>> Monty
>> /me sends jaypipes a fruit basket
> Ok, but in Tokyo you specifically also stated no one should ever remove
> an API because doing so destroyers their users.
> I'm trying to reconcile those points of view.

Getting to a new list of things where there are clear resource names 
that have one and only one set of semantics associated with them is the 
thing I want.

If there are other API endpoints lurking somewhere for backwards compat 
that we don't document and that I can safely ignore - that does not 
bother me.

We should NEVER actually delete a thing - that's only self serving. 
However, we can remove a thing from being a thing we talk about. So, if 
nova has an os-floating-ips for backawards compat, that's neat, but I 
can just always use the neutron floating-ips resource and ignore it.

More information about the OpenStack-dev mailing list