[openstack-dev] [api][nova][ironic] Microversion API HTTP header
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>:
>>> 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
> 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.
More information about the OpenStack-dev