On 06/25/2015 05:33 PM, Anne Gentle wrote:


On Thu, Jun 25, 2015 at 7:10 AM, Sean Dague <s...@dague.net
<mailto:s...@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
    <lucasago...@gmail.com <mailto:lucasago...@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-requ...@lists.openstack.org?subject:unsubscribe
    <http://openstack-dev-requ...@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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev



__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Reply via email to