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

Anne Gentle annegentle at justwriteclick.com
Thu Jun 25 16:04:48 UTC 2015


On Thu, Jun 25, 2015 at 10:55 AM, Dmitry Tantsur <dtantsur at redhat.com>
wrote:

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


I have been supporting developer end users on the Rackspace cloud for
nearly four years now. I gave a talk in Paris at the Summit about
supporting developers. Developers using cloud resources expect to use
computing power or storage capacity to accomplish a broader task. Nova and
swift have nothing to do with their expectations.


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

This "ironic-inspector" has just come across my path. Can you talk more
about what people do with it? Inspect compute nodes for bare metal
capability?


>
>
>> 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
>>
>>
>
> __________________________________________________________________________
> 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/7e7710dc/attachment.html>


More information about the OpenStack-dev mailing list