Open Stack

On Thu, Jun 25, 2015 at 7:10 AM, Sean Dague <sean at dague.net> wrote:

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

We already have X-OpenStack-Request-ID as a header in the Compute v2.1 API
for helping to track requests and troubleshoot.

So I agree with Sean that we need to think across more APIs but there is
precedence set for "OpenStack-" as a keyword to look for in responses.

Also I hadn't discovered X-OpenStack-Nova-API-Version until now -- and I
don't think that we should use project names in end-user-facing messaging,
ever. They then have to do a look up for "nova" among over 20 project
names. [1] Since that got unmarked experimental can it be re-marked
experimental?

My suggestion:

X-OpenStack-Compute-API-Version
X-OpenStack-Containers-API-Version
X-OpenStack-Baremetal-API-Version
X-OpenStack-Blockstorage-API-Version
X-OpenStack-Image-API-Version
X-OpenStack-Identity-API-Version

I'm going to get VERY specific about how we name projects and the service
they provide in projects.yaml. We simply cannot put users through the hell
of "what's the boomstick project and why does it not have a version I need?"

Anne

1.
https://wiki.openstack.org/wiki/Documentation/Conventions#Service_and_project_names
2.
https://git.openstack.org/cgit/openstack/governance/tree/reference/projects.yaml





>
>         -Sean
>
> --
> Sean Dague
> http://dague.net
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150625/f4deba93/attachment.html>