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

Jay Pipes jaypipes at gmail.com
Mon Feb 8 14:46:06 UTC 2016

On 02/08/2016 07:13 AM, Sean Dague wrote:
> 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?

Hard work. The kind of collaboration needed here is hard, sometimes 
boring work. But it's absolutely necessary, IMHO. And we, as a 
community, have simply punted on making these hard decisions, and we're 
worse off for it.

The TC should have as a project acceptance criteria a clause about REST 
API overlap or replacement. I feel strongly about this and so have 
started a patch with a resolution to the governance repo around this.

> 2) is there buy in from both communities?

I don't really care if there is or there isn't. This is something that 
is vital to the long-term reputation of OpenStack.

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

Sorry, I'm not quite following you. I'm not proposing that we focus on 
defining a single API. I'm not proposing that we help each project to 
implement that API.

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

Please read the point below. I specifically said that overlaps in 
top-level resources should be handled in one of three ways (alignment, 
renaming or placed under a sub-resource). You have shown the third 
option above: placing the overlapping top-level resources as a sub-resource.

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

There simply should not be 2 slightly different and incompatible 
"OpenStack Telemetry API"s. The fact that there currently is makes any 
talk of "backwards compatibility" a non-sequitur.

What precisely is going to be "backwards incompatible" if we continue to 
have 2 OpenStack Telemetry APIs that are slightly different and 
inconsistent with each other?

Also, I never agreed to anything that said you can never remove an API, 
ever. I clearly think that backwards compatibility is a major concern, 
but not being able to deprecate and move forward ever is something that 
I think is a bridge too far. We should be able to lift the 
compute_api_min_version at some point in the future. Software isn't 
static. Neither are users. Both adapt given a documented and long-enough 


More information about the OpenStack-dev mailing list