[openstack-dev] [api][nova][ironic] Microversion API HTTP header

Sean Dague sean at dague.net
Thu Jun 25 12:10:37 UTC 2015

On 06/25/2015 04:42 AM, Ken'ichi Ohmichi wrote:
> 2015-06-25 17:25 GMT+09:00 Lucas Alvares Gomes <lucasagomes at gmail.com>:
>> Hi,
>>> If renaming "Ironic" to the other, is it still necessary to keep the
>>> name in the header?
>>> There are some projects which are already renamed like Neutron, Zaqar
>>> and the others.
>>> So "OpenStack-API-Version" which doesn't contain project name seems
>>> reasonable for me.
>> I don't think we should make decisions base on those cases, these are
>> exceptions.
> I don't think so.
> Renames of projects have already happened too many time even if we can
> say "they are exceptions".
> In big tent, the renames will happen more.
>> But even if it happens the name in the header is the least
>> problematic thing. When a project is renamed, apart from the massive
>> refactor in the code other things have to change, packaging, service
>> files, etc...
> Internal implementation(like packaging, service files, directory
> structures, etc) is not matter for end users at all.
> API header is an interface between services to end users.
> The area of influence of API header is much bigger than the implementation.
> Now I can see the first Jay's point.
> Yeah, Nova and Ironic are implementations, and we cannot say "The
> implementation rename never happens." because Neutron has happened.
>> For the headers you could have both, one with the old
>> name and one with the new name for a while to give people time to
>> migrate and then remove the old name. Just like deprecating other
>> stuff, e.g a configuration option.
> That seems painful to end users.
> So what is disagreeing point against "OpenStack-API-Version" here?

My concern remains that there is no such thing as an
OpenStack-API-Version. There is no place to look it up. It's like asking
for the OpenStack Database Version. This is a construct which is project
scoped, and makes no sense outside of that project.

For someone that's extremely familiar with what they are doing, they'll
understand that http://service.provider/compute is Nova, and can find
their way to Nova docs on the API. But for new folks, I can only see
this adding to confusion.

Being extra, and possibly redundantly, explicit here eliminates
confusion. Our API is communication to our users, and I feel like at
every point we should err on the side of what's going to be the most
clear under the largest number of scenarios.


Sean Dague

More information about the OpenStack-dev mailing list