Open Stack

On 06/25/2015 05:33 PM, Anne Gentle wrote:
>
>
> On Thu, Jun 25, 2015 at 7:10 AM, Sean Dague <sean at dague.net
> <mailto: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 <mailto: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?

I'm not sure where the assumption comes from that people will know 
"compute" better than "nova". In my experience I've never seen *users* 
referring to "the baremetal service", which is not surprising for people 
installing `openstack-ironic-*` packages, then using `ironic` utility or 
`ironicclient` python module to access the API, while using 
http://docs.openstack.org/developer/ironic/ as documentation. We 
probably should change all of these before we can safely assume that 
users would prefer "the baremetal service".

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

The same question as above: what to do with services that do not have a 
blessed name (e.g. my ironic-inspector)?

>
> 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://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe>
>     http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
>
>
> --
> Anne Gentle
> Rackspace
> Principal Engineer
> www.justwriteclick.com <http://www.justwriteclick.com>
>
>
> __________________________________________________________________________
> 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
>