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

Sean Dague sean at dague.net
Mon Feb 8 12:13:46 UTC 2016

On 02/07/2016 08: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.
> 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.
> 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.

1) how do you imagine this happening?

2) is there buy in from both communities?

3) 2 implementations of 1 API that is actually semantically the same is
super hard. Doing so in the IETF typically takes many years.

I feel like we spent a bunch of time a couple years ago putting projects
detailed improvement plans from the TC, and it really didn't go all that
well. The outside-in approach without community buy in mostly just gets
combative and hostile.

> * 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/

It feels really early to run down a path here on trying to build a
registry for top level resources when we've yet to get service types down.

Also, I'm not hugely sure why:

GET /compute/flavors
GET /dataprocessing/flavors
GET /queues/flavors

Is the worst thing we could be doing. And while I get the idea that in a
perfect world there would be no overlap, the cost of getting there in
breaking working software seems... a bit of a bad tradeoff.

> * 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

And what happens to all the software out there written to OpenStack? I
do get the concerns for coherency, at the same time randomly changing
API interfaces on people is a great way to kick all your users in the
knees and take their candy.

At the last summit basically *exactly* the opposite was agreed to. You
don't get to remove an API, ever. Because the moment it's out there, it
has users.


Sean Dague

More information about the OpenStack-dev mailing list