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

[Bruno Morel]

+1 on all of Jay's conclusions. :)

I¹m pretty new to OpenStack, but not at all to API, REST API, and web
development in general, and I concur : ŒNova¹, ŒSwift¹, ŒKeystone¹ and so
on makes it very hard to learn how things work in OpenStack and what each
of those parts are responsible with.
I¹ll be honest, I had to print this schema
(http://getcloudify.org/img/blog/openstackdiagram.jpg) and put the name on
it to be able to sort myself out of it. :)
I would also agree that projects/teams can keep their secret Œin the
family¹ name for differentiation (and also facilitate coopetition) and
tools, but I would love to be able to abstract it at some level (the
service level seems perfect for that).


As a dev, this get my votes. All of them in fact :)
As long as we can agree on the function of each service and associate a
name that has a natural don¹t-need-a-map-to-get-it, I¹m all for it.


Best,

Bruno Morel
Internap / iWeb Technologies

On 2015-07-05, 11:45, "Jay Pipes"  wrote:

>On 06/25/2015 02:19 PM, Monty Taylor wrote:
>> On 06/25/2015 01:35 PM, Devananda van der Veen wrote:
>>> Sean's point and Dmitri's are similar.
>>>
>>> There are APIs for projects which do not have official team or
>>>"program"
>>> names. And some teams may produce more than one forward-facing service.
>>> Naming the API based in the team name doesn't make sense.
>>>
>>> My previous point is that restricting the API name to the team/program
>>>name
>>> will prevent any competition among projects. It'll be impossibly
>>>confusing
>>> to users if more than one "monitoring" project exists, they all have
>>> different API, but each claim to be the one true
>>>OpenStack-Monitoring-API
>>
>> I believe that it is important that there is only one api in OpenStack
>> that provides a given short name. Even with the big tent.
>
>So do I. I've been saying that for quite some time. Which is why I've
>been arguing for referring to things like they are referred to on the
>API documentation site:
>
>http://developer.openstack.org/#api
>
>By the name of the API, which is "The OpenStack Compute API", not "The
>Nova API".
>
>> I say that because, as a user, I ask the service catalog for a well
>> known service type - "compute" or "baremetal" or "network" - and I get
>> back a REST endpoint that is ostensibly for that purpose.
>
>Precisely correct.
>
>> If I then have to introspect that service to find out what it really is,
>> we have fully jumped the shark and started prioritizing our own
>> navel-gazing over any hope of any human ever using what we're doing.
>>
>> So - yes, this is potentially, although not actually, a problem right
>> now. And we need to solve it before it moves from being an actual
>>problem.
>
>Right. Which is why I was trying to prevent this problem from becoming
>bigger than it needs to be, and trying to convince people to use the
>service type that appears in the Keystone Service Catalog as the {NAME}
>in X-OpenStack-{NAME}-API-Version header.
>
>Best,
>-jay
>
>>> On Jun 25, 2015 9:37 AM, "Sean Dague"  wrote:
>>>
 On 06/25/2015 12:04 PM, Anne Gentle wrote:
>
>
> On Thu, Jun 25, 2015 at 10:55 AM, Dmitry Tantsur  > wrote:
 
>
>
>  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.

 That's good feedback, and clearly moves the needle in my head.

 It also does open up a question about the big tent nature, because
it's
 unclear what projects that do not yet have a generic name allocated to
 them would use.

  -Sean

 --
 Sean Dague
 http://dague.net

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

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

[Jay Pipes]

On 06/25/2015 02:19 PM, Monty Taylor wrote:

On 06/25/2015 01:35 PM, Devananda van der Veen wrote:

Sean's point and Dmitri's are similar.

There are APIs for projects which do not have official team or "program"
names. And some teams may produce more than one forward-facing service.
Naming the API based in the team name doesn't make sense.

My previous point is that restricting the API name to the team/program name
will prevent any competition among projects. It'll be impossibly confusing
to users if more than one "monitoring" project exists, they all have
different API, but each claim to be the one true OpenStack-Monitoring-API


I believe that it is important that there is only one api in OpenStack
that provides a given short name. Even with the big tent.


So do I. I've been saying that for quite some time. Which is why I've 
been arguing for referring to things like they are referred to on the 
API documentation site:


http://developer.openstack.org/#api

By the name of the API, which is "The OpenStack Compute API", not "The 
Nova API".



I say that because, as a user, I ask the service catalog for a well
known service type - "compute" or "baremetal" or "network" - and I get
back a REST endpoint that is ostensibly for that purpose.


Precisely correct.


If I then have to introspect that service to find out what it really is,
we have fully jumped the shark and started prioritizing our own
navel-gazing over any hope of any human ever using what we're doing.

So - yes, this is potentially, although not actually, a problem right
now. And we need to solve it before it moves from being an actual problem.


Right. Which is why I was trying to prevent this problem from becoming 
bigger than it needs to be, and trying to convince people to use the 
service type that appears in the Keystone Service Catalog as the {NAME} 
in X-OpenStack-{NAME}-API-Version header.


Best,
-jay


On Jun 25, 2015 9:37 AM, "Sean Dague"  wrote:


On 06/25/2015 12:04 PM, Anne Gentle wrote:



On Thu, Jun 25, 2015 at 10:55 AM, Dmitry Tantsur mailto:dtant...@redhat.com>> wrote:





 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.


That's good feedback, and clearly moves the needle in my head.

It also does open up a question about the big tent nature, because it's
unclear what projects that do not yet have a generic name allocated to
them would use.

 -Sean

--
Sean Dague
http://dague.net

__
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




__
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

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

[Dean Troyer]

On Mon, Jun 29, 2015 at 7:41 PM, Ken'ichi Ohmichi 
wrote:

> Yeah, I had the same thinking.
> Based on it, we can remove generic name(compute, identity, etc) from
> API microversions header.
>

I'm not certain we want to remove the name, but to use the type field as
the value of the name in the header.


> I tend to prefer generic name(compute, identity, etc) because the name
> seems stable.
>

+1

dt

-- 

Dean Troyer
dtro...@gmail.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

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

[Ken'ichi Ohmichi]

2015-06-26 4:21 GMT+09:00 Dean Troyer :
> On Thu, Jun 25, 2015 at 7:10 AM, Sean Dague  wrote:
>>
>> 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.
>
>
> Anyone using the REST API directly has already gotten an endpoint from the
> service catalog using the service type (I'm ignoring the deprecated 'name'
> field).  The version header should match up directly to the type used to get
> the endpoint.

Yeah, I had the same thinking.
Based on it, we can remove generic name(compute, identity, etc) from
API microversions header.

But now I feel it is fine to use the generic name if the name is
allocated quickly just after a project is created and the name is
stable.
JSON-Home also needs something for representing each project in a
response payload like:

http://docs.openstack.org/api/openstack-identity/3/rel
http://docs.openstack.org/api/openstack-compute/2.1/rel

for the relationship.
So even if we can remove the name from microversion header, we need
something for representing each project.
I tend to prefer generic name(compute, identity, etc) because the name
seems stable.

I push this to api-wg guidline[1] for cross projects.

Thanks
Ken Ohmichi

---

[1]: https://review.openstack.org/#/c/196918/

__
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

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

[Dean Troyer]

On Thu, Jun 25, 2015 at 7:10 AM, Sean Dague  wrote:

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

Anyone using the REST API directly has already gotten an endpoint from the
service catalog using the service type (I'm ignoring the deprecated 'name'
field).  The version header should match up directly to the type used to
get the endpoint.


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

I agree with this sentiment, and extra hard in that we need to be as
consistent across all of out APIs as possible.

dt

-- 

Dean Troyer
dtro...@gmail.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

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

[Monty Taylor]

On 06/25/2015 01:35 PM, Devananda van der Veen wrote:
> Sean's point and Dmitri's are similar.
> 
> There are APIs for projects which do not have official team or "program"
> names. And some teams may produce more than one forward-facing service.
> Naming the API based in the team name doesn't make sense.
> 
> My previous point is that restricting the API name to the team/program name
> will prevent any competition among projects. It'll be impossibly confusing
> to users if more than one "monitoring" project exists, they all have
> different API, but each claim to be the one true OpenStack-Monitoring-API

I believe that it is important that there is only one api in OpenStack
that provides a given short name. Even with the big tent.

I say that because, as a user, I ask the service catalog for a well
known service type - "compute" or "baremetal" or "network" - and I get
back a REST endpoint that is ostensibly for that purpose.

If I then have to introspect that service to find out what it really is,
we have fully jumped the shark and started prioritizing our own
navel-gazing over any hope of any human ever using what we're doing.

So - yes, this is potentially, although not actually, a problem right
now. And we need to solve it before it moves from being an actual problem.

> On Jun 25, 2015 9:37 AM, "Sean Dague"  wrote:
> 
>> On 06/25/2015 12:04 PM, Anne Gentle wrote:
>>>
>>>
>>> On Thu, Jun 25, 2015 at 10:55 AM, Dmitry Tantsur >> > wrote:
>> 
>>>
>>>
>>> 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.
>>
>> That's good feedback, and clearly moves the needle in my head.
>>
>> It also does open up a question about the big tent nature, because it's
>> unclear what projects that do not yet have a generic name allocated to
>> them would use.
>>
>> -Sean
>>
>> --
>> Sean Dague
>> http://dague.net
>>
>> __
>> 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
> 


__
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

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

[Devananda van der Veen]

Sean's point and Dmitri's are similar.

There are APIs for projects which do not have official team or "program"
names. And some teams may produce more than one forward-facing service.
Naming the API based in the team name doesn't make sense.

My previous point is that restricting the API name to the team/program name
will prevent any competition among projects. It'll be impossibly confusing
to users if more than one "monitoring" project exists, they all have
different API, but each claim to be the one true OpenStack-Monitoring-API

-Deva
On Jun 25, 2015 9:37 AM, "Sean Dague"  wrote:

> On 06/25/2015 12:04 PM, Anne Gentle wrote:
> >
> >
> > On Thu, Jun 25, 2015 at 10:55 AM, Dmitry Tantsur  > > wrote:
> 
> >
> >
> > 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.
>
> That's good feedback, and clearly moves the needle in my head.
>
> It also does open up a question about the big tent nature, because it's
> unclear what projects that do not yet have a generic name allocated to
> them would use.
>
> -Sean
>
> --
> Sean Dague
> http://dague.net
>
> __
> 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

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

[Sean Dague]

On 06/25/2015 12:04 PM, Anne Gentle wrote:
> 
> 
> On Thu, Jun 25, 2015 at 10:55 AM, Dmitry Tantsur  > wrote:

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

That's good feedback, and clearly moves the needle in my head.

It also does open up a question about the big tent nature, because it's
unclear what projects that do not yet have a generic name allocated to
them would use.

-Sean

-- 
Sean Dague
http://dague.net

__
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

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

[Dmitry Tantsur]

On 06/25/2015 06:04 PM, Anne Gentle wrote:



On Thu, Jun 25, 2015 at 10:55 AM, Dmitry Tantsur mailto:dtant...@redhat.com>> wrote:

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



On Thu, Jun 25, 2015 at 7:10 AM, Sean Dague 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
 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".


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 surpri

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

[Anne Gentle]

On Thu, Jun 25, 2015 at 10:55 AM, Dmitry Tantsur 
wrote:

> On 06/25/2015 05:33 PM, Anne Gentle wrote:
>
>>
>>
>> On Thu, Jun 25, 2015 at 7:10 AM, Sean Dague > > wrote:
>>
>> On 06/25/2015 04:42 AM, Ken'ichi Ohmichi wrote:
>>  > 2015-06-25 17:25 GMT+09:00 Lucas Alvares Gomes
>> 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".


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

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

[Dmitry Tantsur]

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



On Thu, Jun 25, 2015 at 7:10 AM, Sean Dague 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
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

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

[Jay Pipes]

On 06/25/2015 11:33 AM, Anne Gentle wrote:

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


Right. That was my original proposal that Ironic deviated from, and then 
Nova changed to match Ironic.


-jay

__
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

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

[Anne Gentle]

On Thu, Jun 25, 2015 at 7:10 AM, Sean Dague  wrote:

> On 06/25/2015 04:42 AM, Ken'ichi Ohmichi wrote:
> > 2015-06-25 17:25 GMT+09:00 Lucas Alvares Gomes :
> >> 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-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 
Anne Gentle
Rackspace
Principal Engineer
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

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

[Sean Dague]

On 06/25/2015 04:42 AM, Ken'ichi Ohmichi wrote:
> 2015-06-25 17:25 GMT+09:00 Lucas Alvares Gomes :
>> 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.

-Sean

-- 
Sean Dague
http://dague.net

__
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

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

[Ken'ichi Ohmichi]

2015-06-25 17:25 GMT+09:00 Lucas Alvares Gomes :
> 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?

Thanks
Ken Ohmichi

__
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

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

[Lucas Alvares Gomes]

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

Cheers,
Lucas

__
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

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

[Ken'ichi Ohmichi]

2015-06-20 4:40 GMT+09:00 Devananda van der Veen :
>>
>> > * We have a vendor endpoint. This endpoint allows vendor to extend our
>> > API to expose new hardware capabilities that aren't present in the
>> > core API. Once multiple vendors starts implementing the same feature
>> > on this endpoint we then decide whether to promote it to the core API.
>>
>> This is a problem. The above means that there is no single OpenStack
>> BareMetal API. This means developers that want to write against an
>> OpenStack BareMetal API cannot rely on different deployments of Ironic
>> exposing the same API. That is a recipe for a lack of interoperability
>> and decreased developer ease of use.
>
> Nope - not a problem. Actually it's been really helpful. We've found this to
> be a better way to implement driver extensions -- it's clearly *not* part of
> Ironic's API, and it's communicated as such in the API itself.
>
> Any standard part of Ironic's functionality is exposed in the standard API,
> and hardware-specific extensions, which are not supported by enough vendors
> to be standardized yet, are only exposed through the vendor-specific API
> endpoint. It's very clear in the REST API what this is -- the end points
> are, for example,
>
>   GET /v1/nodes//vendor_passthru/methods
>   POST /v1/nodes//vendor_passthru?method=foo¶m=bar
>
>   GET /v1/drivers//methods
>
> ... and so on. This provides a mechanism to discover what resources and
> methods said hardware vendor exposes in their hardware driver. We have
> always supported out of tree drivers, and it is possible to upgrade Ironic
> without upgrading the driver (or vice versa).
>
> Also to note, our client library doesn't support any of the vendor-specific
> methods, and never will. It only supports Ironic's API's ability to
> *discover* what vendor-specific methods that driver exposes, and then to
> transparently call to them. And none of that is relevant to other OpenStack
> projects.
>
> So if an operator wants to write a custom app that uses foo-vendor's
> advanced-foo-making capabilities because they only buy Foo hardware --
> that's great. They can do that. Presumably, they have a support contract
> with Foo vendor. Ironic is merely providing the transport between them.
>
>
>>
>>
>> > * There's a "reservation" attribute in the Node's resource [1] which
>> > valueis the hostname of the conductor that is currently holding an
>> > exclusive lock to act upon this node. This is because internally we
>> > use a distributed hashing algorithm to be able to route the requests
>> > from the API service to a conductor service that is able to manage
>> > that Node. And having this field in the API
>>
>> That is just leaking implementation inappropriately out of the public
>> REST API, and shouldn't be encouraged, IMHO. Nova has a number of these
>> leaky parts of its API, too, of course. Just look at the os-guests API
>> extension, which only works when you're using Xen under the hood,
>> thereby leaking implementation details about the underlying
>> infrastructure out through the public REST API.
>
>
> yes, this is leaky in the purest sense, but remember that ironic doesn't
> expose a *public* API. Only operators and other services should be talking
> directly to it -- and this field was requested by operators who find it
> helpful to know which service has locked a resource.
>
>>
>> > I don't think that any of those decisions were bad by the way, this
>> > have helped us a lot to understand how a service to manage Bare Metal
>> > machines should looks like, and we have made wrong decisions too (You
>> > can get the same information by GET'ing different endpoints in the
>> > API, the Chassis resources currently have no usage apart from
>> > logically grouping nodes, etc...)
>>
>> Sure, all APIs have warts :) But the warts aren't an excuse to delay
>> plugging up those leaks.
>>
>>
>> > So back to the topic. if we are removing the project name from the
>> > Header to facilitate another project to implement the these type of
>> > APIs I don't think it will help much. Perhaps the API-WG group should
>> > make say that for new API's the microversion Header should not have
>> > the projects name in it. Because then, I think we can think about an
>> > API definition that is decouple from the implementation.
>>
>> Sure.
>>
>
> Unless the API-WG is going to actually define the API for every project (or
> the TC wants to do that), I don't think we can remove the project name from
> the header.
>
> If another *project team* wanted to implement a Baremetal Service, and they
> were required to use the "OpenStack-Baremetal-API-Version" -- or the
> "OpenStack-API-Version" -- headers, and assuming they don't want to be
> sitting second fiddle to the incumbent project's API changes (I mean, if
> they wanted that, why go make a new project?) it would be difficult for any
> user to tell the two apart. Imagine a new service returning a lower version
> number for the same version hea

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

[Rochelle Grober]

In line (at the bottom)

From: Devananda van der Veen [mailto:devananda@gmail.com]
Sent: Friday, June 19, 2015 12:40
To: OpenStack Development Mailing List (not for usage questions)
Subject: Re: [openstack-dev] [api][nova][ironic] Microversion API HTTP header


On Wed, Jun 17, 2015 at 7:31 AM Jay Pipes 
mailto:jaypi...@gmail.com>> wrote:
On 06/17/2015 06:30 AM, Lucas Alvares Gomes wrote:
>> overlap there rather than competition), how crazy does it sound if we say
>> that for OpenStack Nova is the compute API and Ironic the Bare Metal API and
>> so on? Would that be an unacceptable power grab?
>
> It's not that it's unacceptable, but I think that things weren't
> projected that way. Jay started this thread with this sentence:
>
> "To be blunt, Nova is the *implementation* of the OpenStack Compute
> API. Ironic is the *implementation* of the OpenStack BareMetal API."
>
> Which I don't think is totally correct, at least for Ironic. The
> Ironic's API have evolved and shaped as we implemented Ironic, I think
> that some decisions we made in the API makes it clear, e.g:
>
> * Resources have JSON attributes. If you look at some attributes of
> the resources you will see that they are just a JSON blob. That's by
> design because we didn't know exactly how the API should look like and
> so by having these JSON fields it allows us to easily extend the
> resource without changing it's structure [1] (see driver_info,
> instance_info, extra)

OK. Nothing wrong with that.

> * We have a vendor endpoint. This endpoint allows vendor to extend our
> API to expose new hardware capabilities that aren't present in the
> core API. Once multiple vendors starts implementing the same feature
> on this endpoint we then decide whether to promote it to the core API.

This is a problem. The above means that there is no single OpenStack
BareMetal API. This means developers that want to write against an
OpenStack BareMetal API cannot rely on different deployments of Ironic
exposing the same API. That is a recipe for a lack of interoperability
and decreased developer ease of use.

Nope - not a problem. Actually it's been really helpful. We've found this to be 
a better way to implement driver extensions -- it's clearly *not* part of 
Ironic's API, and it's communicated as such in the API itself.

Any standard part of Ironic's functionality is exposed in the standard API, and 
hardware-specific extensions, which are not supported by enough vendors to be 
standardized yet, are only exposed through the vendor-specific API endpoint. 
It's very clear in the REST API what this is -- the end points are, for example,

  GET /v1/nodes//vendor_passthru/methods
  POST /v1/nodes//vendor_passthru?method=foo¶m=bar

  GET /v1/drivers//methods

... and so on. This provides a mechanism to discover what resources and methods 
said hardware vendor exposes in their hardware driver. We have always supported 
out of tree drivers, and it is possible to upgrade Ironic without upgrading the 
driver (or vice versa).

Also to note, our client library doesn't support any of the vendor-specific 
methods, and never will. It only supports Ironic's API's ability to *discover* 
what vendor-specific methods that driver exposes, and then to transparently 
call to them. And none of that is relevant to other OpenStack projects.

So if an operator wants to write a custom app that uses foo-vendor's 
advanced-foo-making capabilities because they only buy Foo hardware -- that's 
great. They can do that. Presumably, they have a support contract with Foo 
vendor. Ironic is merely providing the transport between them.



> * There's a "reservation" attribute in the Node's resource [1] which
> valueis the hostname of the conductor that is currently holding an
> exclusive lock to act upon this node. This is because internally we
> use a distributed hashing algorithm to be able to route the requests
> from the API service to a conductor service that is able to manage
> that Node. And having this field in the API

That is just leaking implementation inappropriately out of the public
REST API, and shouldn't be encouraged, IMHO. Nova has a number of these
leaky parts of its API, too, of course. Just look at the os-guests API
extension, which only works when you're using Xen under the hood,
thereby leaking implementation details about the underlying
infrastructure out through the public REST API.

yes, this is leaky in the purest sense, but remember that ironic doesn't expose 
a *public* API. Only operators and other services should be talking directly to 
it -- and this field was requested by operators who find it helpful to know 
which service has locked a resource.


> I don't think that any of those deci

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

[Devananda van der Veen]

On Wed, Jun 17, 2015 at 7:31 AM Jay Pipes  wrote:

> On 06/17/2015 06:30 AM, Lucas Alvares Gomes wrote:
> >> overlap there rather than competition), how crazy does it sound if we
> say
> >> that for OpenStack Nova is the compute API and Ironic the Bare Metal
> API and
> >> so on? Would that be an unacceptable power grab?
> >
> > It's not that it's unacceptable, but I think that things weren't
> > projected that way. Jay started this thread with this sentence:
> >
> > "To be blunt, Nova is the *implementation* of the OpenStack Compute
> > API. Ironic is the *implementation* of the OpenStack BareMetal API."
> >
> > Which I don't think is totally correct, at least for Ironic. The
> > Ironic's API have evolved and shaped as we implemented Ironic, I think
> > that some decisions we made in the API makes it clear, e.g:
> >
> > * Resources have JSON attributes. If you look at some attributes of
> > the resources you will see that they are just a JSON blob. That's by
> > design because we didn't know exactly how the API should look like and
> > so by having these JSON fields it allows us to easily extend the
> > resource without changing it's structure [1] (see driver_info,
> > instance_info, extra)
>
> OK. Nothing wrong with that.
>
> > * We have a vendor endpoint. This endpoint allows vendor to extend our
> > API to expose new hardware capabilities that aren't present in the
> > core API. Once multiple vendors starts implementing the same feature
> > on this endpoint we then decide whether to promote it to the core API.
>
> This is a problem. The above means that there is no single OpenStack
> BareMetal API. This means developers that want to write against an
> OpenStack BareMetal API cannot rely on different deployments of Ironic
> exposing the same API. That is a recipe for a lack of interoperability
> and decreased developer ease of use.
>

Nope - not a problem. Actually it's been really helpful. We've found this
to be a better way to implement driver extensions -- it's clearly *not*
part of Ironic's API, and it's communicated as such in the API itself.

Any standard part of Ironic's functionality is exposed in the standard API,
and hardware-specific extensions, which are not supported by enough vendors
to be standardized yet, are only exposed through the vendor-specific API
endpoint. It's very clear in the REST API what this is -- the end points
are, for example,

  GET /v1/nodes//vendor_passthru/methods
  POST /v1/nodes//vendor_passthru?method=foo¶m=bar

  GET /v1/drivers//methods

... and so on. This provides a mechanism to discover what resources and
methods said hardware vendor exposes in their hardware driver. We have
always supported out of tree drivers, and it is possible to upgrade Ironic
without upgrading the driver (or vice versa).

Also to note, our client library doesn't support any of the vendor-specific
methods, and never will. It only supports Ironic's API's ability to
*discover* what vendor-specific methods that driver exposes, and then to
transparently call to them. And none of that is relevant to other OpenStack
projects.

So if an operator wants to write a custom app that uses foo-vendor's
advanced-foo-making capabilities because they only buy Foo hardware --
that's great. They can do that. Presumably, they have a support contract
with Foo vendor. Ironic is merely providing the transport between them.



>
> > * There's a "reservation" attribute in the Node's resource [1] which
> > valueis the hostname of the conductor that is currently holding an
> > exclusive lock to act upon this node. This is because internally we
> > use a distributed hashing algorithm to be able to route the requests
> > from the API service to a conductor service that is able to manage
> > that Node. And having this field in the API
>
> That is just leaking implementation inappropriately out of the public
> REST API, and shouldn't be encouraged, IMHO. Nova has a number of these
> leaky parts of its API, too, of course. Just look at the os-guests API
> extension, which only works when you're using Xen under the hood,
> thereby leaking implementation details about the underlying
> infrastructure out through the public REST API.
>

yes, this is leaky in the purest sense, but remember that ironic doesn't
expose a *public* API. Only operators and other services should be talking
directly to it -- and this field was requested by operators who find it
helpful to know which service has locked a resource.


> > I don't think that any of those decisions were bad by the way, this
> > have helped us a lot to understand how a service to manage Bare Metal
> > machines should looks like, and we have made wrong decisions too (You
> > can get the same information by GET'ing different endpoints in the
> > API, the Chassis resources currently have no usage apart from
> > logically grouping nodes, etc...)
>
> Sure, all APIs have warts :) But the warts aren't an excuse to delay
> plugging up those leaks.


> > So back to the

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

[Jay Pipes]

On 06/17/2015 06:30 AM, Lucas Alvares Gomes wrote:

overlap there rather than competition), how crazy does it sound if we say
that for OpenStack Nova is the compute API and Ironic the Bare Metal API and
so on? Would that be an unacceptable power grab?


It's not that it's unacceptable, but I think that things weren't
projected that way. Jay started this thread with this sentence:

"To be blunt, Nova is the *implementation* of the OpenStack Compute
API. Ironic is the *implementation* of the OpenStack BareMetal API."

Which I don't think is totally correct, at least for Ironic. The
Ironic's API have evolved and shaped as we implemented Ironic, I think
that some decisions we made in the API makes it clear, e.g:

* Resources have JSON attributes. If you look at some attributes of
the resources you will see that they are just a JSON blob. That's by
design because we didn't know exactly how the API should look like and
so by having these JSON fields it allows us to easily extend the
resource without changing it's structure [1] (see driver_info,
instance_info, extra)


OK. Nothing wrong with that.


* We have a vendor endpoint. This endpoint allows vendor to extend our
API to expose new hardware capabilities that aren't present in the
core API. Once multiple vendors starts implementing the same feature
on this endpoint we then decide whether to promote it to the core API.


This is a problem. The above means that there is no single OpenStack 
BareMetal API. This means developers that want to write against an 
OpenStack BareMetal API cannot rely on different deployments of Ironic 
exposing the same API. That is a recipe for a lack of interoperability 
and decreased developer ease of use.



* There's a "reservation" attribute in the Node's resource [1] which
valueis the hostname of the conductor that is currently holding an
exclusive lock to act upon this node. This is because internally we
use a distributed hashing algorithm to be able to route the requests
from the API service to a conductor service that is able to manage
that Node. And having this field in the API


That is just leaking implementation inappropriately out of the public 
REST API, and shouldn't be encouraged, IMHO. Nova has a number of these 
leaky parts of its API, too, of course. Just look at the os-guests API 
extension, which only works when you're using Xen under the hood, 
thereby leaking implementation details about the underlying 
infrastructure out through the public REST API.



I don't think that any of those decisions were bad by the way, this
have helped us a lot to understand how a service to manage Bare Metal
machines should looks like, and we have made wrong decisions too (You
can get the same information by GET'ing different endpoints in the
API, the Chassis resources currently have no usage apart from
logically grouping nodes, etc...)


Sure, all APIs have warts :) But the warts aren't an excuse to delay 
plugging up those leaks.



So back to the topic. if we are removing the project name from the
Header to facilitate another project to implement the these type of
APIs I don't think it will help much. Perhaps the API-WG group should
make say that for new API's the microversion Header should not have
the projects name in it. Because then, I think we can think about an
API definition that is decouple from the implementation.


Sure.

Best,
-jay

__
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

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

[Alex Xu]

2015-06-17 19:46 GMT+08:00 Andrey Kurilin :

> Why does alternative implementation need to implement all 50 versions?
> As far as I understand, API side should not support all versions, that is
> why version info returns min and max versions
> https://github.com/openstack/nova/blob/master/doc/api_samples/versions/versions-get-resp.json#L25-L26
>

If we raise min_versions randomly...that may means we have 50
back-incompatible APIs in the world. So min_version will be raise rarely
for keep back-compatible


>
>
> On Tue, Jun 16, 2015 at 11:36 AM, Alex Xu  wrote:
>
>>
>>
>> 2015-06-16 5:24 GMT+08:00 Clint Byrum :
>>
>>> Excerpts from Sean Dague's message of 2015-06-15 14:00:43 -0700:
>>> > On 06/15/2015 04:50 PM, Jim Rollenhagen wrote:
>>> > > On Mon, Jun 15, 2015 at 01:07:39PM -0400, Jay Pipes wrote:
>>> > >> It has come to my attention in [1] that the microversion spec for
>>> Nova [2]
>>> > >> and Ironic [3] have used the project name -- i.e. Nova and Ironic
>>> -- instead
>>> > >> of the name of the API -- i.e. "OpenStack Compute" and "OpenStack
>>> Bare
>>> > >> Metal" -- in the HTTP header that a client passes to indicate a
>>> preference
>>> > >> for or knowledge of a particular API microversion.
>>> > >>
>>> > >> The original spec said that the HTTP header should contain the name
>>> of the
>>> > >> service type returned by the Keystone service catalog (which is
>>> also the
>>> > >> official name of the REST API). I don't understand why the spec was
>>> changed
>>> > >> retroactively and why Nova has been changed to return
>>> > >> X-OpenStack-Nova-API-Version instead of
>>> X-OpenStack-Compute-API-Version HTTP
>>> > >> headers [4].
>>> > >>
>>> > >> To be blunt, Nova is the *implementation* of the OpenStack Compute
>>> API.
>>> > >> Ironic is the *implementation* of the OpenStack BareMetal API.
>>> > >
>>> > > While I tend to agree in principle, do we reasonably expect that
>>> other
>>> > > implementations of these APIs will implement every one of these
>>> > > versions? Can we even reasonably expect another implementation of
>>> these
>>> > > APIs?
>>> > >
>>> > > // jim
>>> >
>>> > Yeh, honestly, I'm not really convinced that thinking we are doing this
>>> > for alternative implementations is really the right approach (or even
>>> > desireable). Honestly, the transition to microversions makes
>>> alternative
>>> > implementations harder because there isn't a big frozen API for a long
>>> > period of time.
>>> >
>>>
>>> Actually that makes an alternative implementation more valuable. Without
>>> microversions those alternative implementations would have to wait a long
>>> time to implement fixes to the API, but now can implement and publish
>>> the fix as soon as the microversion lands. This means that alternative
>>> implementations will lag _less_ behind the primary.
>>>
>>
>> So if our min_version is 2.1 and the max_version is 2.50. That means
>> alternative implementations need implement all the 50 versions api...that
>> sounds pain...
>>
>>
>>>
>>>
>>> __
>>> 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
>>
>>
>
>
> --
> Best regards,
> Andrey Kurilin.
>
> __
> 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

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

[Andrey Kurilin]

Why does alternative implementation need to implement all 50 versions?
As far as I understand, API side should not support all versions, that is
why version info returns min and max versions
https://github.com/openstack/nova/blob/master/doc/api_samples/versions/versions-get-resp.json#L25-L26

On Tue, Jun 16, 2015 at 11:36 AM, Alex Xu  wrote:

>
>
> 2015-06-16 5:24 GMT+08:00 Clint Byrum :
>
>> Excerpts from Sean Dague's message of 2015-06-15 14:00:43 -0700:
>> > On 06/15/2015 04:50 PM, Jim Rollenhagen wrote:
>> > > On Mon, Jun 15, 2015 at 01:07:39PM -0400, Jay Pipes wrote:
>> > >> It has come to my attention in [1] that the microversion spec for
>> Nova [2]
>> > >> and Ironic [3] have used the project name -- i.e. Nova and Ironic --
>> instead
>> > >> of the name of the API -- i.e. "OpenStack Compute" and "OpenStack
>> Bare
>> > >> Metal" -- in the HTTP header that a client passes to indicate a
>> preference
>> > >> for or knowledge of a particular API microversion.
>> > >>
>> > >> The original spec said that the HTTP header should contain the name
>> of the
>> > >> service type returned by the Keystone service catalog (which is also
>> the
>> > >> official name of the REST API). I don't understand why the spec was
>> changed
>> > >> retroactively and why Nova has been changed to return
>> > >> X-OpenStack-Nova-API-Version instead of
>> X-OpenStack-Compute-API-Version HTTP
>> > >> headers [4].
>> > >>
>> > >> To be blunt, Nova is the *implementation* of the OpenStack Compute
>> API.
>> > >> Ironic is the *implementation* of the OpenStack BareMetal API.
>> > >
>> > > While I tend to agree in principle, do we reasonably expect that other
>> > > implementations of these APIs will implement every one of these
>> > > versions? Can we even reasonably expect another implementation of
>> these
>> > > APIs?
>> > >
>> > > // jim
>> >
>> > Yeh, honestly, I'm not really convinced that thinking we are doing this
>> > for alternative implementations is really the right approach (or even
>> > desireable). Honestly, the transition to microversions makes alternative
>> > implementations harder because there isn't a big frozen API for a long
>> > period of time.
>> >
>>
>> Actually that makes an alternative implementation more valuable. Without
>> microversions those alternative implementations would have to wait a long
>> time to implement fixes to the API, but now can implement and publish
>> the fix as soon as the microversion lands. This means that alternative
>> implementations will lag _less_ behind the primary.
>>
>
> So if our min_version is 2.1 and the max_version is 2.50. That means
> alternative implementations need implement all the 50 versions api...that
> sounds pain...
>
>
>>
>> __
>> 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
>
>


-- 
Best regards,
Andrey Kurilin.
__
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

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

[Lucas Alvares Gomes]

Hi,

I don't want to have to diverge much from the topic of this thread,
I've done this already as pointed out by Sean. But I feel like
replying to this.

>> Sorry I might be missing something. I don't think one thing justify
>> the other, plus the problem seems to be the source of truth. I thought
>> that the idea of big tent in OpenStack was to not having TC to "pick
>> winners". E.g, If someone wants to have an alternative implementation
>> of the Baremetal service they will always have to follow Ironic's API?
>> That's unfair, cause they will always be behind and mostly likely
>> won't weight much on the decisions of the API.
>
>
> I agree and at the same I disagree with this statement.
>
> A competing project in the Baremetal (or networking, or pop-corn as a
> service) areas, can move into two directions:
> 1) Providing a different implementation for the same API that the
> "incumbent" (Ironic in this case) provides.
> 2) Supply different paradigms, including a different user API, thus
> presenting itself as a "new way" of doing Baremetal (and this is exactly
> what Quantum did to nova-network).
>
> Both cases are valid, I believe.
> In the first case, the advantage is that operators could switch between the
> various implementations without affecting their users (this does not mean
> that the switch won't be painful for them of course). Also, users shouldn't
> have to worry about what's implementing the service, as they always interact
> with the same API.
> However, it creates a problem regarding control of said API... the team from
> the "incumbent" project, the new team, both teams, the API-WG, or no-one?
> The second case is super-painful for both operators and users (do you need a
> refresh on the nova-network vs neutron saga? We're at the 5th series now,
> and the end is not even in sight) However, it completely avoid the
> governance problem arising from having APIs which are implemented by
> multiple projects.
>

Right, I wasn't considering 2) because I thought it was out of the
table for this discussion.

>> As I mentioned in the other reply, I find it difficult to talk about
>> alternative implementations while we do not decouple the API
>> definition level from the implementation level. If we want alternative
>> implementations to be a real competitor we need to have a sorta of
>> program in OpenStack that will be responsible for delivering a
>> reference API for each type of project (Baremetal, Compute, Identity,
>> and so on...).
>
>
> Indeed. If I understood what you wrote correctly, this is in-line with what
> I stated in the previous paragraph.
> Nevertheless, since afaict we do not have any competing APIs at the moment
> (the nova-network API is part of the Nova API so we might be talking about
> overlap there rather than competition), how crazy does it sound if we say
> that for OpenStack Nova is the compute API and Ironic the Bare Metal API and
> so on? Would that be an unacceptable power grab?

It's not that it's unacceptable, but I think that things weren't
projected that way. Jay started this thread with this sentence:

"To be blunt, Nova is the *implementation* of the OpenStack Compute
API. Ironic is the *implementation* of the OpenStack BareMetal API."

Which I don't think is totally correct, at least for Ironic. The
Ironic's API have evolved and shaped as we implemented Ironic, I think
that some decisions we made in the API makes it clear, e.g:

* Resources have JSON attributes. If you look at some attributes of
the resources you will see that they are just a JSON blob. That's by
design because we didn't know exactly how the API should look like and
so by having these JSON fields it allows us to easily extend the
resource without changing it's structure [1] (see driver_info,
instance_info, extra)

* We have a vendor endpoint. This endpoint allows vendor to extend our
API to expose new hardware capabilities that aren't present in the
core API. Once multiple vendors starts implementing the same feature
on this endpoint we then decide whether to promote it to the core API.

* There's a "reservation" attribute in the Node's resource [1] which
valueis the hostname of the conductor that is currently holding an
exclusive lock to act upon this node. This is because internally we
use a distributed hashing algorithm to be able to route the requests
from the API service to a conductor service that is able to manage
that Node. And having this field in the API

I don't think that any of those decisions were bad by the way, this
have helped us a lot to understand how a service to manage Bare Metal
machines should looks like, and we have made wrong decisions too (You
can get the same information by GET'ing different endpoints in the
API, the Chassis resources currently have no usage apart from
logically grouping nodes, etc...)

So back to the topic. if we are removing the project name from the
Header to facilitate another project to implement the these type of
APIs I don't think it will hel

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

[Dmitry Tantsur]

On 06/17/2015 03:35 AM, Ken'ichi Ohmichi wrote:

2015-06-16 21:16 GMT+09:00 Jay Pipes :

On 06/16/2015 08:00 AM, Dmitry Tantsur wrote:



16 июня 2015 г. 13:52 пользователь "Jay Pipes" mailto:jaypi...@gmail.com>> написал:
  >
  > On 06/16/2015 04:36 AM, Alex Xu wrote:
  >>
  >> So if our min_version is 2.1 and the max_version is 2.50. That means
  >> alternative implementations need implement all the 50 versions
  >> api...that sounds pain...
  >
  >
  > Yes, it's pain, but it's no different than someone who is following
the Amazon EC2 API, which cuts releases at a regular (sometimes every
2-3 weeks) clip.
  >
  > In Amazon-land, the releases are date-based, instead of
microversion/incrementing version-based, but the idea is essentially the
same.
  >
  > There is GREAT value to having an API mean ONE thing and ONE thing
only. It means that developers can code against something that isn't
like quicksand -- constantly changing meanings.

Being one of such developers, I only see this "value" for breaking
changes.



Sorry, Dmitry, I'm not quite following you. Could you elaborate on what you
mean by above?


I guess maybe he is thinking the value of microversions is just for
backwards incompatible changes and backwards compatible changes are
unnecessary to be managed by microversions because he is proposing it
as Ironic patch.


Exactly. That's not only my thinking, that's my experience from Kilo as 
both Ironic developer, and developer *for* Ironic (i.e. the very person 
you're trying to make happy).




Thanks
Ken Ohmichi

__
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

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

[Ken'ichi Ohmichi]

2015-06-16 21:14 GMT+09:00 Sean Dague :
> On 06/16/2015 07:38 AM, Alex Xu wrote:
>>
>>
>> 2015-06-16 18:57 GMT+08:00 Sean Dague > >:
>>
>> On 06/15/2015 03:45 PM, Kevin L. Mitchell wrote:
>> > On Mon, 2015-06-15 at 13:07 -0400, Jay Pipes wrote:
>> >> The original spec said that the HTTP header should contain the name of
>> >> the service type returned by the Keystone service catalog (which is 
>> also
>> >> the official name of the REST API). I don't understand why the spec 
>> was
>> >> changed retroactively and why Nova has been changed to return
>> >> X-OpenStack-Nova-API-Version instead of 
>> X-OpenStack-Compute-API-Version
>> >> HTTP headers [4].
>> >
>> > Given the disagreement evinced by the responses to this thread, let me
>> > ask a question: Would there be any particular problem with using
>> > "X-OpenStack-API-Version"?
>>
>> So, here is my concern with not having the project namespacing at all:
>>
>> Our expectation is that services are going to move towards real wsgi on
>> their API instead of eventlet. Which is, hopefully, naturally going to
>> give you things like this:
>>
>> GET api.server/compute/servers
>> GET api.server/baremetal/chasis
>>
>> In such a world it will end up possibly confusing that
>> OpenStack-API-Version 2.500 is returned from api.server/compute/servers,
>> but OpenStack-API-Version 1.200 is returned from
>> api.server/baremetal/chasis.
>>
>>
>> Client should get those url from keystone SC, that means client should
>> know what he request to.
>
> Sure, there is a lot of should in there though. But by removing a level
> of explicitness in this we potentially introduce more confusion. The
> goal of a good interface is not just to make it easy to use, but make it
> hard to misuse. Being explicit about the service in the return header
> will eliminate a class of errors where the client code got confused
> about which service they were talking to (because to setup a VM with a
> network in a neutron case you have to jump back and forth between Nova /
> Neutron quite a bit).

Does here mean Nova will be able to pass Neutron's microversion to
Neutron on a single Nova API call?
I feel Nova should not do it because in this case Neutron is a backend
and Neutron should disappear from end user POV on Nova API.
If backend services are not visible from end users POV, the users
cannot know the range of backend service microversions.
And if acceptable to pass microversion to backend service, the out of
microversion range error would happen and that would make users more
confused.

Thanks
Ken Ohmichi

__
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

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

[Ken'ichi Ohmichi]

2015-06-16 21:16 GMT+09:00 Jay Pipes :
> On 06/16/2015 08:00 AM, Dmitry Tantsur wrote:
>>
>>
>> 16 июня 2015 г. 13:52 пользователь "Jay Pipes" > > написал:
>>  >
>>  > On 06/16/2015 04:36 AM, Alex Xu wrote:
>>  >>
>>  >> So if our min_version is 2.1 and the max_version is 2.50. That means
>>  >> alternative implementations need implement all the 50 versions
>>  >> api...that sounds pain...
>>  >
>>  >
>>  > Yes, it's pain, but it's no different than someone who is following
>> the Amazon EC2 API, which cuts releases at a regular (sometimes every
>> 2-3 weeks) clip.
>>  >
>>  > In Amazon-land, the releases are date-based, instead of
>> microversion/incrementing version-based, but the idea is essentially the
>> same.
>>  >
>>  > There is GREAT value to having an API mean ONE thing and ONE thing
>> only. It means that developers can code against something that isn't
>> like quicksand -- constantly changing meanings.
>>
>> Being one of such developers, I only see this "value" for breaking
>> changes.
>
>
> Sorry, Dmitry, I'm not quite following you. Could you elaborate on what you
> mean by above?

I guess maybe he is thinking the value of microversions is just for
backwards incompatible changes and backwards compatible changes are
unnecessary to be managed by microversions because he is proposing it
as Ironic patch.

Thanks
Ken Ohmichi

__
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

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

[Ken'ichi Ohmichi]

2015-06-16 20:52 GMT+09:00 Jay Pipes :
>
>> but I have the same question with Dmitry.
>> If using service names in the header, how to define these name before
>> that?
>> Current big-tent situation can make duplications between projects like
>> X-OpenStack-Container-API-Version or something.
>> Project names are unique even if they are just implementations.
>
>
> Well, I actually like Kevin's suggestion of just removing the
> project/service-type altogether and using OpenStack-API-Version, but to
> answer your question above, I'd just say that having a single API for
> "OpenStack Containers" has value. See my previous responses about why having
> the API mean a single thing allows developers to better use our APIs.

Thanks for your reply, I got it.
I also prefer Kevin's idea, that will be nice to use in all projects.

Thanks
Ken Ohmichi

__
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

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

[Ken'ichi Ohmichi]

2015-06-16 6:30 GMT+09:00 Michael Davies :
> On Tue, Jun 16, 2015 at 5:15 AM, Kevin L. Mitchell
>  wrote:
>>
>> Given the disagreement evinced by the responses to this thread, let me
>> ask a question: Would there be any particular problem with using
>> "X-OpenStack-API-Version"?
>
>
> Well, perhaps we should consider "OpenStack-API-Version" instead and drop
> the "X-".  Ref https://tools.ietf.org/html/rfc6648.

OpenStack-API-Version seems short, simple and consistent.
So +1

Thanks
Ken Ohmichi

__
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

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

[Salvatore Orlando]

On 16 June 2015 at 14:38, Lucas Alvares Gomes  wrote:

> Hi
>
> >> So if our min_version is 2.1 and the max_version is 2.50. That means
> >> alternative implementations need implement all the 50 versions
> >> api...that sounds pain...
> >
> >
> > Yes, it's pain, but it's no different than someone who is following the
> > Amazon EC2 API, which cuts releases at a regular (sometimes every 2-3
> weeks)
> > clip.
> >
> > In Amazon-land, the releases are date-based, instead of
> > microversion/incrementing version-based, but the idea is essentially the
> > same.
> >
>
> Sorry I might be missing something. I don't think one thing justify
> the other, plus the problem seems to be the source of truth. I thought
> that the idea of big tent in OpenStack was to not having TC to "pick
> winners". E.g, If someone wants to have an alternative implementation
> of the Baremetal service they will always have to follow Ironic's API?
> That's unfair, cause they will always be behind and mostly likely
> won't weight much on the decisions of the API.
>

I agree and at the same I disagree with this statement.

A competing project in the Baremetal (or networking, or pop-corn as a
service) areas, can move into two directions:
1) Providing a different implementation for the same API that the
"incumbent" (Ironic in this case) provides.
2) Supply different paradigms, including a different user API, thus
presenting itself as a "new way" of doing Baremetal (and this is exactly
what Quantum did to nova-network).

Both cases are valid, I believe.
In the first case, the advantage is that operators could switch between the
various implementations without affecting their users (this does not mean
that the switch won't be painful for them of course). Also, users shouldn't
have to worry about what's implementing the service, as they always
interact with the same API.
However, it creates a problem regarding control of said API... the team
from the "incumbent" project, the new team, both teams, the API-WG, or
no-one?
The second case is super-painful for both operators and users (do you need
a refresh on the nova-network vs neutron saga? We're at the 5th series now,
and the end is not even in sight) However, it completely avoid the
governance problem arising from having APIs which are implemented by
multiple projects.

So, even I understand where Jay is coming from, and ideally I'd love to
have APIs associated with app catalog elements rather than projects, I
think there is not yet a model that would allow to achieve this when
multiple API implementations are present. So I also understand why the
headers have been implemented in the current way.



>
> As I mentioned in the other reply, I find it difficult to talk about
> alternative implementations while we do not decouple the API
> definition level from the implementation level. If we want alternative
> implementations to be a real competitor we need to have a sorta of
> program in OpenStack that will be responsible for delivering a
> reference API for each type of project (Baremetal, Compute, Identity,
> and so on...).
>

Indeed. If I understood what you wrote correctly, this is in-line with what
I stated in the previous paragraph.
Nevertheless, since afaict we do not have any competing APIs at the moment
(the nova-network API is part of the Nova API so we might be talking about
overlap there rather than competition), how crazy does it sound if we say
that for OpenStack Nova is the compute API and Ironic the Bare Metal API
and so on? Would that be an unacceptable power grab?


>
> > There is GREAT value to having an API mean ONE thing and ONE thing only.
> It
> > means that developers can code against something that isn't like
> quicksand
> > -- constantly changing meanings.
>
> +1, sure.
>
> Cheers,
> Lucas
>
> __
> 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

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

[Sean Dague]

On 06/16/2015 08:38 AM, Lucas Alvares Gomes wrote:
> Hi
> 
>>> So if our min_version is 2.1 and the max_version is 2.50. That means
>>> alternative implementations need implement all the 50 versions
>>> api...that sounds pain...
>>
>>
>> Yes, it's pain, but it's no different than someone who is following the
>> Amazon EC2 API, which cuts releases at a regular (sometimes every 2-3 weeks)
>> clip.
>>
>> In Amazon-land, the releases are date-based, instead of
>> microversion/incrementing version-based, but the idea is essentially the
>> same.
>>
> 
> Sorry I might be missing something. I don't think one thing justify
> the other, plus the problem seems to be the source of truth. I thought
> that the idea of big tent in OpenStack was to not having TC to "pick
> winners". E.g, If someone wants to have an alternative implementation
> of the Baremetal service they will always have to follow Ironic's API?
> That's unfair, cause they will always be behind and mostly likely
> won't weight much on the decisions of the API.
> 
> As I mentioned in the other reply, I find it difficult to talk about
> alternative implementations while we do not decouple the API
> definition level from the implementation level. If we want alternative
> implementations to be a real competitor we need to have a sorta of
> program in OpenStack that will be responsible for delivering a
> reference API for each type of project (Baremetal, Compute, Identity,
> and so on...).

I kind of feel like we've sprung up a completely unrelated conversation
about what big tent means under a pretty narrow question about 'what
should this header be called, and if/when should we change it now that
it's in the field'. I've probably contributed to it drifting off topic
as well.

However, I think it would be good to try to focus on the topic at hand
which is header naming, what the implications are, and if/when changes
should happen.

The goal of Microversions was crisping up the API contract to the user
across multiple deploys, at different points in time, of the *same*
upstream codebase. That's the narrow problem we are trying to fix. It's
not a grandious API abstraction. It might let us get to one down the
road, now that we can evolve the API one bit at a time. But that's a
down the road thing.

So in that context we have a current header which references a service
by code name.

The plus side of that is we've already got a central registry for what
that should be, openstack/{name}.

Also the problem with expanding to generic names is with Neutron you get
OpenStack-Network-API-Version but there are multiple network
implementations still. Or even worse, what if Congress and or GBP
implement microversions? OpenStack-Policy-API-Version? What about
projects that start off outside of openstack/ and implement this kind of
mechanism, so either don't have a moniker, or land grab one that we're
not comfortable with them having inside of OpenStack.

So I don't think it's clear that in the general case the generic moniker
is better than the code name one. And it's a change to a thing in the
field, so I feel like deciding on that kind of change is probably a
thing we need to make sure we really think the change will be beneficial
to our stake holders, API consumers, Operators, Developers, Integrators.

On a change like this I'd much rather not preoptimize for out of tree
re-implementations, which I think we've said pretty strongly at a TC
level that we don't want, and instead leave the status quo until there
is a strong reason that benefits once of our stake holders.

-Sean

-- 
Sean Dague
http://dague.net

__
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

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

[Lucas Alvares Gomes]

Hi

>> So if our min_version is 2.1 and the max_version is 2.50. That means
>> alternative implementations need implement all the 50 versions
>> api...that sounds pain...
>
>
> Yes, it's pain, but it's no different than someone who is following the
> Amazon EC2 API, which cuts releases at a regular (sometimes every 2-3 weeks)
> clip.
>
> In Amazon-land, the releases are date-based, instead of
> microversion/incrementing version-based, but the idea is essentially the
> same.
>

Sorry I might be missing something. I don't think one thing justify
the other, plus the problem seems to be the source of truth. I thought
that the idea of big tent in OpenStack was to not having TC to "pick
winners". E.g, If someone wants to have an alternative implementation
of the Baremetal service they will always have to follow Ironic's API?
That's unfair, cause they will always be behind and mostly likely
won't weight much on the decisions of the API.

As I mentioned in the other reply, I find it difficult to talk about
alternative implementations while we do not decouple the API
definition level from the implementation level. If we want alternative
implementations to be a real competitor we need to have a sorta of
program in OpenStack that will be responsible for delivering a
reference API for each type of project (Baremetal, Compute, Identity,
and so on...).

> There is GREAT value to having an API mean ONE thing and ONE thing only. It
> means that developers can code against something that isn't like quicksand
> -- constantly changing meanings.

+1, sure.

Cheers,
Lucas

__
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

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

[Jay Pipes]

On 06/16/2015 08:00 AM, Dmitry Tantsur wrote:


16 июня 2015 г. 13:52 пользователь "Jay Pipes" mailto:jaypi...@gmail.com>> написал:
 >
 > On 06/16/2015 04:36 AM, Alex Xu wrote:
 >>
 >> So if our min_version is 2.1 and the max_version is 2.50. That means
 >> alternative implementations need implement all the 50 versions
 >> api...that sounds pain...
 >
 >
 > Yes, it's pain, but it's no different than someone who is following
the Amazon EC2 API, which cuts releases at a regular (sometimes every
2-3 weeks) clip.
 >
 > In Amazon-land, the releases are date-based, instead of
microversion/incrementing version-based, but the idea is essentially the
same.
 >
 > There is GREAT value to having an API mean ONE thing and ONE thing
only. It means that developers can code against something that isn't
like quicksand -- constantly changing meanings.

Being one of such developers, I only see this "value" for breaking changes.


Sorry, Dmitry, I'm not quite following you. Could you elaborate on what 
you mean by above?


Thanks,
-jay

__
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

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

[Sean Dague]

On 06/16/2015 07:38 AM, Alex Xu wrote:
> 
> 
> 2015-06-16 18:57 GMT+08:00 Sean Dague  >:
> 
> On 06/15/2015 03:45 PM, Kevin L. Mitchell wrote:
> > On Mon, 2015-06-15 at 13:07 -0400, Jay Pipes wrote:
> >> The original spec said that the HTTP header should contain the name of
> >> the service type returned by the Keystone service catalog (which is 
> also
> >> the official name of the REST API). I don't understand why the spec was
> >> changed retroactively and why Nova has been changed to return
> >> X-OpenStack-Nova-API-Version instead of X-OpenStack-Compute-API-Version
> >> HTTP headers [4].
> >
> > Given the disagreement evinced by the responses to this thread, let me
> > ask a question: Would there be any particular problem with using
> > "X-OpenStack-API-Version"?
> 
> So, here is my concern with not having the project namespacing at all:
> 
> Our expectation is that services are going to move towards real wsgi on
> their API instead of eventlet. Which is, hopefully, naturally going to
> give you things like this:
> 
> GET api.server/compute/servers
> GET api.server/baremetal/chasis
> 
> In such a world it will end up possibly confusing that
> OpenStack-API-Version 2.500 is returned from api.server/compute/servers,
> but OpenStack-API-Version 1.200 is returned from
> api.server/baremetal/chasis.
> 
> 
> Client should get those url from keystone SC, that means client should
> know what he request to.

Sure, there is a lot of should in there though. But by removing a level
of explicitness in this we potentially introduce more confusion. The
goal of a good interface is not just to make it easy to use, but make it
hard to misuse. Being explicit about the service in the return header
will eliminate a class of errors where the client code got confused
about which service they were talking to (because to setup a VM with a
network in a neutron case you have to jump back and forth between Nova /
Neutron quite a bit).

This would provide an additional bit of signaling on that fact, which
will prevent a class of mistakes by API consumers.

-Sean

-- 
Sean Dague
http://dague.net

__
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

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

[Dmitry Tantsur]

16 июня 2015 г. 13:52 пользователь "Jay Pipes"  написал:
>
> On 06/16/2015 04:36 AM, Alex Xu wrote:
>>
>> So if our min_version is 2.1 and the max_version is 2.50. That means
>> alternative implementations need implement all the 50 versions
>> api...that sounds pain...
>
>
> Yes, it's pain, but it's no different than someone who is following the
Amazon EC2 API, which cuts releases at a regular (sometimes every 2-3
weeks) clip.
>
> In Amazon-land, the releases are date-based, instead of
microversion/incrementing version-based, but the idea is essentially the
same.
>
> There is GREAT value to having an API mean ONE thing and ONE thing only.
It means that developers can code against something that isn't like
quicksand -- constantly changing meanings.

Being one of such developers, I only see this "value" for breaking changes.

>
> Best,
> -jay
>
>
> __
> 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

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

[Jay Pipes]

On 06/16/2015 04:12 AM, Ken'ichi Ohmichi wrote:

2015-06-16 2:07 GMT+09:00 Jay Pipes :

It has come to my attention in [1] that the microversion spec for Nova [2]
and Ironic [3] have used the project name -- i.e. Nova and Ironic -- instead
of the name of the API -- i.e. "OpenStack Compute" and "OpenStack Bare
Metal" -- in the HTTP header that a client passes to indicate a preference
for or knowledge of a particular API microversion.

The original spec said that the HTTP header should contain the name of the
service type returned by the Keystone service catalog (which is also the
official name of the REST API). I don't understand why the spec was changed
retroactively and why Nova has been changed to return
X-OpenStack-Nova-API-Version instead of X-OpenStack-Compute-API-Version HTTP
headers [4].

To be blunt, Nova is the *implementation* of the OpenStack Compute API.
Ironic is the *implementation* of the OpenStack BareMetal API.

The HTTP headers should never have been changed like this, IMHO, and I'm
disappointed that they were. In fact, it looks like a very select group of
individuals pushed through this change [5] with little to no input from the
mailing list or community.


Yeah, that is my regret now. Sorry about that.
It was better to take conversation more on ml or some place.


I apologize for making you feel bad about it, that wasn't my intent, 
Ken'ichi. :(



but I have the same question with Dmitry.
If using service names in the header, how to define these name before that?
Current big-tent situation can make duplications between projects like
X-OpenStack-Container-API-Version or something.
Project names are unique even if they are just implementations.


Well, I actually like Kevin's suggestion of just removing the 
project/service-type altogether and using OpenStack-API-Version, but to 
answer your question above, I'd just say that having a single API for 
"OpenStack Containers" has value. See my previous responses about why 
having the API mean a single thing allows developers to better use our APIs.



Since no support for these headers has yet to land in the client packages,
can we please reconsider this?


IMO, I am fine to change them if we build a consensus about that.
My main concern is just consistency between projects.


Understood.


In addition, Tempest also doesn't support/test microversions at all yet.
So it seems good timing to reconsider it now.


Good point,
-jay

__
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

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

[Jay Pipes]

On 06/16/2015 04:36 AM, Alex Xu wrote:

So if our min_version is 2.1 and the max_version is 2.50. That means
alternative implementations need implement all the 50 versions
api...that sounds pain...


Yes, it's pain, but it's no different than someone who is following the 
Amazon EC2 API, which cuts releases at a regular (sometimes every 2-3 
weeks) clip.


In Amazon-land, the releases are date-based, instead of 
microversion/incrementing version-based, but the idea is essentially the 
same.


There is GREAT value to having an API mean ONE thing and ONE thing only. 
It means that developers can code against something that isn't like 
quicksand -- constantly changing meanings.


Best,
-jay

__
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

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

[Alex Xu]

2015-06-16 18:57 GMT+08:00 Sean Dague :

> On 06/15/2015 03:45 PM, Kevin L. Mitchell wrote:
> > On Mon, 2015-06-15 at 13:07 -0400, Jay Pipes wrote:
> >> The original spec said that the HTTP header should contain the name of
> >> the service type returned by the Keystone service catalog (which is also
> >> the official name of the REST API). I don't understand why the spec was
> >> changed retroactively and why Nova has been changed to return
> >> X-OpenStack-Nova-API-Version instead of X-OpenStack-Compute-API-Version
> >> HTTP headers [4].
> >
> > Given the disagreement evinced by the responses to this thread, let me
> > ask a question: Would there be any particular problem with using
> > "X-OpenStack-API-Version"?
>
> So, here is my concern with not having the project namespacing at all:
>
> Our expectation is that services are going to move towards real wsgi on
> their API instead of eventlet. Which is, hopefully, naturally going to
> give you things like this:
>
> GET api.server/compute/servers
> GET api.server/baremetal/chasis
>
> In such a world it will end up possibly confusing that
> OpenStack-API-Version 2.500 is returned from api.server/compute/servers,
> but OpenStack-API-Version 1.200 is returned from
> api.server/baremetal/chasis.
>

Client should get those url from keystone SC, that means client should know
what he request to.


>
> From an outsider looking in that seems very unexpected.
>
> So I think we still need service level namespacing on the version header
> for clarity of understanding by application writers, by people filing
> support tickets, and by people running these services.
>
> -Sean
>
> --
> Sean Dague
> http://dague.net
>
> __
> 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

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

[Sean Dague]

On 06/15/2015 03:45 PM, Kevin L. Mitchell wrote:
> On Mon, 2015-06-15 at 13:07 -0400, Jay Pipes wrote:
>> The original spec said that the HTTP header should contain the name of 
>> the service type returned by the Keystone service catalog (which is also 
>> the official name of the REST API). I don't understand why the spec was 
>> changed retroactively and why Nova has been changed to return 
>> X-OpenStack-Nova-API-Version instead of X-OpenStack-Compute-API-Version 
>> HTTP headers [4].
> 
> Given the disagreement evinced by the responses to this thread, let me
> ask a question: Would there be any particular problem with using
> "X-OpenStack-API-Version"?

So, here is my concern with not having the project namespacing at all:

Our expectation is that services are going to move towards real wsgi on
their API instead of eventlet. Which is, hopefully, naturally going to
give you things like this:

GET api.server/compute/servers
GET api.server/baremetal/chasis

In such a world it will end up possibly confusing that
OpenStack-API-Version 2.500 is returned from api.server/compute/servers,
but OpenStack-API-Version 1.200 is returned from
api.server/baremetal/chasis.

>From an outsider looking in that seems very unexpected.

So I think we still need service level namespacing on the version header
for clarity of understanding by application writers, by people filing
support tickets, and by people running these services.

-Sean

-- 
Sean Dague
http://dague.net

__
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

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

[Lucas Alvares Gomes]

Hi,

>> Actually that makes an alternative implementation more valuable. Without
>> microversions those alternative implementations would have to wait a long
>> time to implement fixes to the API, but now can implement and publish
>> the fix as soon as the microversion lands. This means that alternative
>> implementations will lag _less_ behind the primary.
>
>
> So if our min_version is 2.1 and the max_version is 2.50. That means
> alternative implementations need implement all the 50 versions api...that
> sounds pain...
>

Yes, it sounds unrealistic.

I think that the alternative implementations will only realistically
work if we had a program in OpenStack that would be responsible for
creating and delivering a reference API for each type of Project
(Compute, Baremetal, Identity, Telemety, etc...), we need a clear
separation of the API definition level from the implementation level.

That said, I'm OK changing the header to not include the project name
but I don't buy the argument about it making alternative
implementations easier.

Cheers,
Lucas

__
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

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

[Alex Xu]

2015-06-16 5:24 GMT+08:00 Clint Byrum :

> Excerpts from Sean Dague's message of 2015-06-15 14:00:43 -0700:
> > On 06/15/2015 04:50 PM, Jim Rollenhagen wrote:
> > > On Mon, Jun 15, 2015 at 01:07:39PM -0400, Jay Pipes wrote:
> > >> It has come to my attention in [1] that the microversion spec for
> Nova [2]
> > >> and Ironic [3] have used the project name -- i.e. Nova and Ironic --
> instead
> > >> of the name of the API -- i.e. "OpenStack Compute" and "OpenStack Bare
> > >> Metal" -- in the HTTP header that a client passes to indicate a
> preference
> > >> for or knowledge of a particular API microversion.
> > >>
> > >> The original spec said that the HTTP header should contain the name
> of the
> > >> service type returned by the Keystone service catalog (which is also
> the
> > >> official name of the REST API). I don't understand why the spec was
> changed
> > >> retroactively and why Nova has been changed to return
> > >> X-OpenStack-Nova-API-Version instead of
> X-OpenStack-Compute-API-Version HTTP
> > >> headers [4].
> > >>
> > >> To be blunt, Nova is the *implementation* of the OpenStack Compute
> API.
> > >> Ironic is the *implementation* of the OpenStack BareMetal API.
> > >
> > > While I tend to agree in principle, do we reasonably expect that other
> > > implementations of these APIs will implement every one of these
> > > versions? Can we even reasonably expect another implementation of these
> > > APIs?
> > >
> > > // jim
> >
> > Yeh, honestly, I'm not really convinced that thinking we are doing this
> > for alternative implementations is really the right approach (or even
> > desireable). Honestly, the transition to microversions makes alternative
> > implementations harder because there isn't a big frozen API for a long
> > period of time.
> >
>
> Actually that makes an alternative implementation more valuable. Without
> microversions those alternative implementations would have to wait a long
> time to implement fixes to the API, but now can implement and publish
> the fix as soon as the microversion lands. This means that alternative
> implementations will lag _less_ behind the primary.
>

So if our min_version is 2.1 and the max_version is 2.50. That means
alternative implementations need implement all the 50 versions api...that
sounds pain...


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

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

[Ken'ichi Ohmichi]

2015-06-16 2:07 GMT+09:00 Jay Pipes :
> It has come to my attention in [1] that the microversion spec for Nova [2]
> and Ironic [3] have used the project name -- i.e. Nova and Ironic -- instead
> of the name of the API -- i.e. "OpenStack Compute" and "OpenStack Bare
> Metal" -- in the HTTP header that a client passes to indicate a preference
> for or knowledge of a particular API microversion.
>
> The original spec said that the HTTP header should contain the name of the
> service type returned by the Keystone service catalog (which is also the
> official name of the REST API). I don't understand why the spec was changed
> retroactively and why Nova has been changed to return
> X-OpenStack-Nova-API-Version instead of X-OpenStack-Compute-API-Version HTTP
> headers [4].
>
> To be blunt, Nova is the *implementation* of the OpenStack Compute API.
> Ironic is the *implementation* of the OpenStack BareMetal API.
>
> The HTTP headers should never have been changed like this, IMHO, and I'm
> disappointed that they were. In fact, it looks like a very select group of
> individuals pushed through this change [5] with little to no input from the
> mailing list or community.

Yeah, that is my regret now. Sorry about that.
It was better to take conversation more on ml or some place.

but I have the same question with Dmitry.
If using service names in the header, how to define these name before that?
Current big-tent situation can make duplications between projects like
X-OpenStack-Container-API-Version or something.
Project names are unique even if they are just implementations.

> Since no support for these headers has yet to land in the client packages,
> can we please reconsider this?

IMO, I am fine to change them if we build a consensus about that.
My main concern is just consistency between projects.

In addition, Tempest also doesn't support/test microversions at all yet.
So it seems good timing to reconsider it now.

Thanks
Ken Ohmichi

__
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

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

[Alex Xu]

2015-06-16 5:58 GMT+08:00 Ed Leafe :

> -BEGIN PGP SIGNED MESSAGE-
> Hash: SHA512
>
> On 06/15/2015 04:30 PM, Michael Davies wrote:
>
> > On Tue, Jun 16, 2015 at 5:15 AM, Kevin L. Mitchell
> >  > > wrote:
> >
> > Given the disagreement evinced by the responses to this thread, let
> > me ask a question: Would there be any particular problem with
> > using "X-OpenStack-API-Version"?
> >
> >
> > Well, perhaps we should consider "OpenStack-API-Version" instead
> > and drop the "X-".  Ref https://tools.ietf.org/html/rfc6648.
>
> That makes the most sense to me.
>

+1 from me too.


>
>
> - --
>
> - -- Ed Leafe
> -BEGIN PGP SIGNATURE-
> Version: GnuPG v2
> Comment: GPGTools - https://gpgtools.org
> Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/
>
> iQIcBAEBCgAGBQJVf0qaAAoJEKMgtcocwZqLadcP/2eha5nAC+F3K72qqIjUf8fo
> yvX05TMD9x8wAbvyJtTggP1Nj+FivAYyyuaer6B4V4bn6PvNeVtJPrdL0imV5ywG
> E4HBJal89zDTtWOXn0y2S9FO+rYioua/sQZY/feYE8HmMxd0pxRLZY5KPbMtq+Ob
> eq5vF6FitczCt4jJg+Cqz8ZJoRa2VFxlXHFSovjZeO5FvYzCwJpu/+rYfYG0sgfK
> 7Cx8M7TKn0cRU861b33hII7Pn/l9oaLOtH8PTmqrPADm1LP3sx5230iP48+RzcS8
> UxfuNPlnGIuHqESk3WPgLW4SRQUDA8ETFmVRQn9iem95IfVQjTGV2MNW0H0RO00R
> 7eyjG9sVVCe9OUz1gDVq8E2n99cX8jyVjWNlxvDY/k+jKW5z1gGnebdC8AD6r5xK
> TPSdY2Pz2b10D7URTavWAfUrUKk0SnH/CMTKh2+p5Z5WOOybn1rg6U/m2nATbQC/
> CDnhY+tAjjEh3Q3esosM6t32JndNKahf/NTsih7reFBtu3CFXsU1WnVEY1HCeY5W
> i9yxJitic2mqjFGFRM4rijDajLH/4jXFoSlFhUq3phePkMn3WE56jsijZZhFKGCp
> 3279+KWI90qDkGvLgamQ0X3AmddZFktX9IlDv1qZM9W38SOLWy/qu7xrsbq6fWvV
> p8UqJwYaKoNl5Hl1hY26
> =VCm4
> -END PGP SIGNATURE-
>
> __
> 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

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

[Dmitry Tantsur]

On 06/15/2015 10:31 PM, Jay Pipes wrote:



On 06/15/2015 02:09 PM, Dmitry Tantsur wrote:



2015-06-15 19:50 GMT+02:00 Clint Byrum mailto:cl...@fewbar.com>>:

Excerpts from Jay Pipes's message of 2015-06-15 10:07:39 -0700:
> It has come to my attention in [1] that the microversion spec
for Nova
> [2] and Ironic [3] have used the project name -- i.e. Nova and
Ironic --
> instead of the name of the API -- i.e. "OpenStack Compute" and
> "OpenStack Bare Metal" -- in the HTTP header that a client
passes to
> indicate a preference for or knowledge of a particular API
microversion.
>
> The original spec said that the HTTP header should contain the
name of
> the service type returned by the Keystone service catalog (which
is also
> the official name of the REST API). I don't understand why the
spec was
> changed retroactively and why Nova has been changed to return
> X-OpenStack-Nova-API-Version instead of
X-OpenStack-Compute-API-Version
> HTTP headers [4].
>
> To be blunt, Nova is the *implementation* of the OpenStack
Compute API.
> Ironic is the *implementation* of the OpenStack BareMetal API.
>
> The HTTP headers should never have been changed like this, IMHO,
and I'm
> disappointed that they were. In fact, it looks like a very
select group
> of individuals pushed through this change [5] with little to no
input
> from the mailing list or community.
>
> Since no support for these headers has yet to land in the client
> packages, can we please reconsider this?

I tend to agree with you.

The juxtaposition is somewhat surprising. [1] Is cited as the
reason for
making the change, but that governance change is addressing the
way we
govern projects, not API's. The goal of the change itself is to
encourage
competition amongst projects. However, publishing an OpenStack API
with
a project name anywhere in it is the opposite: it discourages
alternative
implementations. If we really believe there are no sacred cows and a
nova
replacement (or proxy, or accelerator, or or or..) could happen
inside the
OpenStack community, then we should be more careful about defining
the API


If Ironic will still be the main authority to define "the baremetal
API", header renaming won't help the alternative implementations.


IMHO, we need to start thinking of the public, versioned REST APIs as
separate from both the implementation as well as the contributor
community that develops the implementation.

Assuming the implementation == the REST API promotes the attitude that
it doesn't really matter what the REST API looks like or how it evolves,
since "the code is the documentation" and "the code is the API". This
does a disservice to the user of the REST API, IMO.


Also, what to use for services, that do not have direct program mapping?
I.e., I'm planning to add microversioning to ironic-inspector. Who is
going to define a proper service name? Myself? The ironic team? Should I
bother the TC?


Does the ironic-inspector expose a REST API?


Yeah, that's why I'm asking :) Only 2 simple endpoints, but still.



-jay


However, if we do believe that Nova and Ironic are special, then
the API
can stand as-is, though I still find it sub-optimal.

I'm a little bit worried that we don't have a guiding principle to
point
at somewhere. Perhaps the API WG can encode guidance either way
("We use
project names", or "we use service types").

[1] https://review.openstack.org/#/c/145740/

 >
 > Thanks,
 > -jay
 >
 > [1] https://review.openstack.org/#/c/187112/
 > [2]
 >

https://github.com/openstack/nova-specs/blob/master/specs/kilo/implemented/api-microversions.rst

 > [3]
 >

https://github.com/openstack/ironic-specs/blob/master/specs/kilo/api-microversions.rst

 > [4] https://review.openstack.org/#/c/155611/
 > [5] https://review.openstack.org/#/c/153183/
 >


__

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




--
--
-- Dmitry Tantsur
--


__

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



__

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

[Davanum Srinivas]

+1 from me to remove 'X-'

-- dims

On Mon, Jun 15, 2015 at 6:18 PM, Jay Pipes  wrote:
> On 06/15/2015 05:58 PM, Ed Leafe wrote:
>>
>> -BEGIN PGP SIGNED MESSAGE-
>> Hash: SHA512
>>
>> On 06/15/2015 04:30 PM, Michael Davies wrote:
>>
>>> On Tue, Jun 16, 2015 at 5:15 AM, Kevin L. Mitchell
>>> >> > wrote:
>>>
>>> Given the disagreement evinced by the responses to this thread, let
>>> me ask a question: Would there be any particular problem with
>>> using "X-OpenStack-API-Version"?
>>>
>>>
>>> Well, perhaps we should consider "OpenStack-API-Version" instead
>>> and drop the "X-".  Ref https://tools.ietf.org/html/rfc6648.
>>
>>
>> That makes the most sense to me.
>
>
> Sure, agreed that a removal of the X- makes sense.
>
> -jay
>
>
> __
> 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



-- 
Davanum Srinivas :: https://twitter.com/dims

__
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

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

[Jay Pipes]

On 06/15/2015 05:58 PM, Ed Leafe wrote:

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA512

On 06/15/2015 04:30 PM, Michael Davies wrote:


On Tue, Jun 16, 2015 at 5:15 AM, Kevin L. Mitchell
mailto:kevin.mitch...@rackspace.com>> wrote:

Given the disagreement evinced by the responses to this thread, let
me ask a question: Would there be any particular problem with
using "X-OpenStack-API-Version"?


Well, perhaps we should consider "OpenStack-API-Version" instead
and drop the "X-".  Ref https://tools.ietf.org/html/rfc6648.


That makes the most sense to me.


Sure, agreed that a removal of the X- makes sense.

-jay

__
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

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

[Ed Leafe]

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA512

On 06/15/2015 04:30 PM, Michael Davies wrote:

> On Tue, Jun 16, 2015 at 5:15 AM, Kevin L. Mitchell 
>  > wrote:
> 
> Given the disagreement evinced by the responses to this thread, let
> me ask a question: Would there be any particular problem with
> using "X-OpenStack-API-Version"?
> 
> 
> Well, perhaps we should consider "OpenStack-API-Version" instead
> and drop the "X-".  Ref https://tools.ietf.org/html/rfc6648.

That makes the most sense to me.


- -- 

- -- Ed Leafe
-BEGIN PGP SIGNATURE-
Version: GnuPG v2
Comment: GPGTools - https://gpgtools.org
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQIcBAEBCgAGBQJVf0qaAAoJEKMgtcocwZqLadcP/2eha5nAC+F3K72qqIjUf8fo
yvX05TMD9x8wAbvyJtTggP1Nj+FivAYyyuaer6B4V4bn6PvNeVtJPrdL0imV5ywG
E4HBJal89zDTtWOXn0y2S9FO+rYioua/sQZY/feYE8HmMxd0pxRLZY5KPbMtq+Ob
eq5vF6FitczCt4jJg+Cqz8ZJoRa2VFxlXHFSovjZeO5FvYzCwJpu/+rYfYG0sgfK
7Cx8M7TKn0cRU861b33hII7Pn/l9oaLOtH8PTmqrPADm1LP3sx5230iP48+RzcS8
UxfuNPlnGIuHqESk3WPgLW4SRQUDA8ETFmVRQn9iem95IfVQjTGV2MNW0H0RO00R
7eyjG9sVVCe9OUz1gDVq8E2n99cX8jyVjWNlxvDY/k+jKW5z1gGnebdC8AD6r5xK
TPSdY2Pz2b10D7URTavWAfUrUKk0SnH/CMTKh2+p5Z5WOOybn1rg6U/m2nATbQC/
CDnhY+tAjjEh3Q3esosM6t32JndNKahf/NTsih7reFBtu3CFXsU1WnVEY1HCeY5W
i9yxJitic2mqjFGFRM4rijDajLH/4jXFoSlFhUq3phePkMn3WE56jsijZZhFKGCp
3279+KWI90qDkGvLgamQ0X3AmddZFktX9IlDv1qZM9W38SOLWy/qu7xrsbq6fWvV
p8UqJwYaKoNl5Hl1hY26
=VCm4
-END PGP SIGNATURE-

__
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

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

[Dolph Mathews]

On Mon, Jun 15, 2015 at 12:07 PM, Jay Pipes  wrote:

> It has come to my attention in [1] that the microversion spec for Nova [2]
> and Ironic [3] have used the project name -- i.e. Nova and Ironic --
> instead of the name of the API -- i.e. "OpenStack Compute" and "OpenStack
> Bare Metal" -- in the HTTP header that a client passes to indicate a
> preference for or knowledge of a particular API microversion.
>
> The original spec said that the HTTP header should contain the name of the
> service type returned by the Keystone service catalog (which is also the
> official name of the REST API). I don't understand why the spec was changed
> retroactively and why Nova has been changed to return
> X-OpenStack-Nova-API-Version instead of X-OpenStack-Compute-API-Version
> HTTP headers [4].
>
> To be blunt, Nova is the *implementation* of the OpenStack Compute API.
> Ironic is the *implementation* of the OpenStack BareMetal API.
>
> The HTTP headers should never have been changed like this, IMHO, and I'm
> disappointed that they were. In fact, it looks like a very select group of
> individuals pushed through this change [5] with little to no input from the
> mailing list or community.
>
> Since no support for these headers has yet to land in the client packages,
> can we please reconsider this?
>
>
+1 Implementations, and thus project names, can be superseded, deprecated,
and replaced. APIs are around forever. If anyone disagrees with that, then
we can have that conversation, but it doesn't look like that happened here.


> Thanks,
> -jay
>
> [1] https://review.openstack.org/#/c/187112/
> [2]
> https://github.com/openstack/nova-specs/blob/master/specs/kilo/implemented/api-microversions.rst
> [3]
> https://github.com/openstack/ironic-specs/blob/master/specs/kilo/api-microversions.rst
> [4] https://review.openstack.org/#/c/155611/
> [5] https://review.openstack.org/#/c/153183/
>
> __
> 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

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

[Michael Davies]

On Tue, Jun 16, 2015 at 5:15 AM, Kevin L. Mitchell <
kevin.mitch...@rackspace.com> wrote:
>
> Given the disagreement evinced by the responses to this thread, let me
> ask a question: Would there be any particular problem with using
> "X-OpenStack-API-Version"?


Well, perhaps we should consider "OpenStack-API-Version" instead and drop
the "X-".  Ref https://tools.ietf.org/html/rfc6648.

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

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

[Clint Byrum]

Excerpts from Sean Dague's message of 2015-06-15 14:00:43 -0700:
> On 06/15/2015 04:50 PM, Jim Rollenhagen wrote:
> > On Mon, Jun 15, 2015 at 01:07:39PM -0400, Jay Pipes wrote:
> >> It has come to my attention in [1] that the microversion spec for Nova [2]
> >> and Ironic [3] have used the project name -- i.e. Nova and Ironic -- 
> >> instead
> >> of the name of the API -- i.e. "OpenStack Compute" and "OpenStack Bare
> >> Metal" -- in the HTTP header that a client passes to indicate a preference
> >> for or knowledge of a particular API microversion.
> >>
> >> The original spec said that the HTTP header should contain the name of the
> >> service type returned by the Keystone service catalog (which is also the
> >> official name of the REST API). I don't understand why the spec was changed
> >> retroactively and why Nova has been changed to return
> >> X-OpenStack-Nova-API-Version instead of X-OpenStack-Compute-API-Version 
> >> HTTP
> >> headers [4].
> >>
> >> To be blunt, Nova is the *implementation* of the OpenStack Compute API.
> >> Ironic is the *implementation* of the OpenStack BareMetal API.
> > 
> > While I tend to agree in principle, do we reasonably expect that other
> > implementations of these APIs will implement every one of these
> > versions? Can we even reasonably expect another implementation of these
> > APIs?
> > 
> > // jim
> 
> Yeh, honestly, I'm not really convinced that thinking we are doing this
> for alternative implementations is really the right approach (or even
> desireable). Honestly, the transition to microversions makes alternative
> implementations harder because there isn't a big frozen API for a long
> period of time.
> 

Actually that makes an alternative implementation more valuable. Without
microversions those alternative implementations would have to wait a long
time to implement fixes to the API, but now can implement and publish
the fix as soon as the microversion lands. This means that alternative
implementations will lag _less_ behind the primary.

__
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

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

[Adam Young]

On 06/15/2015 01:07 PM, Jay Pipes wrote:
It has come to my attention in [1] that the microversion spec for Nova 
[2] and Ironic [3] have used the project name -- i.e. Nova and Ironic 
-- instead of the name of the API -- i.e. "OpenStack Compute" and 
"OpenStack Bare Metal" -- in the HTTP header that a client passes to 
indicate a preference for or knowledge of a particular API microversion.


The original spec said that the HTTP header should contain the name of 
the service type returned by the Keystone service catalog (which is 
also the official name of the REST API). I don't understand why the 
spec was changed retroactively and why Nova has been changed to return 
X-OpenStack-Nova-API-Version instead of 
X-OpenStack-Compute-API-Version HTTP headers [4].


When it comes to enforcing policy for these APIs, what should we 
realistically be matching against?  Thus far, policy ghas been a purely 
internal thing, with only an implicit mapping from the API to the policy 
rule, but I gathered there was a push especially due to microversions to 
make the two more aligned.


At a minimum, I would think that the namespace of the rule should match 
the header, and we've been pushing that the rules should be namespaced 
"identity",  "compute" and so forth.





To be blunt, Nova is the *implementation* of the OpenStack Compute 
API. Ironic is the *implementation* of the OpenStack BareMetal API.


The HTTP headers should never have been changed like this, IMHO, and 
I'm disappointed that they were. In fact, it looks like a very select 
group of individuals pushed through this change [5] with little to no 
input from the mailing list or community.


Since no support for these headers has yet to land in the client 
packages, can we please reconsider this?


Thanks,
-jay

[1] https://review.openstack.org/#/c/187112/
[2] 
https://github.com/openstack/nova-specs/blob/master/specs/kilo/implemented/api-microversions.rst
[3] 
https://github.com/openstack/ironic-specs/blob/master/specs/kilo/api-microversions.rst

[4] https://review.openstack.org/#/c/155611/
[5] https://review.openstack.org/#/c/153183/

__ 


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

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

[Sean Dague]

On 06/15/2015 04:50 PM, Jim Rollenhagen wrote:
> On Mon, Jun 15, 2015 at 01:07:39PM -0400, Jay Pipes wrote:
>> It has come to my attention in [1] that the microversion spec for Nova [2]
>> and Ironic [3] have used the project name -- i.e. Nova and Ironic -- instead
>> of the name of the API -- i.e. "OpenStack Compute" and "OpenStack Bare
>> Metal" -- in the HTTP header that a client passes to indicate a preference
>> for or knowledge of a particular API microversion.
>>
>> The original spec said that the HTTP header should contain the name of the
>> service type returned by the Keystone service catalog (which is also the
>> official name of the REST API). I don't understand why the spec was changed
>> retroactively and why Nova has been changed to return
>> X-OpenStack-Nova-API-Version instead of X-OpenStack-Compute-API-Version HTTP
>> headers [4].
>>
>> To be blunt, Nova is the *implementation* of the OpenStack Compute API.
>> Ironic is the *implementation* of the OpenStack BareMetal API.
> 
> While I tend to agree in principle, do we reasonably expect that other
> implementations of these APIs will implement every one of these
> versions? Can we even reasonably expect another implementation of these
> APIs?
> 
> // jim

Yeh, honestly, I'm not really convinced that thinking we are doing this
for alternative implementations is really the right approach (or even
desireable). Honestly, the transition to microversions makes alternative
implementations harder because there isn't a big frozen API for a long
period of time.

Microversions are about us being honest that the API is going to evolve
with the code, and that we can document and version that evolution very
carefully so that it can be consumed in a deliberate way (and not leave
the consumers randomly guessing). For the same reason we version our
internal RPC payloads and our database versions (which we pair with code).

I'm all for reconsidering what we want to call this header (and yay! we
have a microversioning mechanism by which we could even change that in a
sane way), but I don't think we should rush it, and I definitely don't
think it should be dealt with before we do some more standarization of
the service catalog contents.

-Sean

-- 
Sean Dague
http://dague.net

__
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

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

[Jim Rollenhagen]

On Mon, Jun 15, 2015 at 01:07:39PM -0400, Jay Pipes wrote:
> It has come to my attention in [1] that the microversion spec for Nova [2]
> and Ironic [3] have used the project name -- i.e. Nova and Ironic -- instead
> of the name of the API -- i.e. "OpenStack Compute" and "OpenStack Bare
> Metal" -- in the HTTP header that a client passes to indicate a preference
> for or knowledge of a particular API microversion.
> 
> The original spec said that the HTTP header should contain the name of the
> service type returned by the Keystone service catalog (which is also the
> official name of the REST API). I don't understand why the spec was changed
> retroactively and why Nova has been changed to return
> X-OpenStack-Nova-API-Version instead of X-OpenStack-Compute-API-Version HTTP
> headers [4].
> 
> To be blunt, Nova is the *implementation* of the OpenStack Compute API.
> Ironic is the *implementation* of the OpenStack BareMetal API.

While I tend to agree in principle, do we reasonably expect that other
implementations of these APIs will implement every one of these
versions? Can we even reasonably expect another implementation of these
APIs?

// jim

> 
> The HTTP headers should never have been changed like this, IMHO, and I'm
> disappointed that they were. In fact, it looks like a very select group of
> individuals pushed through this change [5] with little to no input from the
> mailing list or community.
> 
> Since no support for these headers has yet to land in the client packages,
> can we please reconsider this?
> 
> Thanks,
> -jay
> 
> [1] https://review.openstack.org/#/c/187112/
> [2] 
> https://github.com/openstack/nova-specs/blob/master/specs/kilo/implemented/api-microversions.rst
> [3] 
> https://github.com/openstack/ironic-specs/blob/master/specs/kilo/api-microversions.rst
> [4] https://review.openstack.org/#/c/155611/
> [5] https://review.openstack.org/#/c/153183/
> 
> __
> 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

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

[Jay Pipes]

On 06/15/2015 02:26 PM, Ruby Loo wrote:

On 15 June 2015 at 13:07, Jay Pipes mailto:jaypi...@gmail.com>> wrote:

It has come to my attention in [1] that the microversion spec for
Nova [2] and Ironic [3] have used the project name -- i.e. Nova and
Ironic -- instead of the name of the API -- i.e. "OpenStack Compute"
and "OpenStack Bare Metal" -- in the HTTP header that a client
passes to indicate a preference for or knowledge of a particular API
microversion.

The original spec said that the HTTP header should contain the name
of the service type returned by the Keystone service catalog (which
is also the official name of the REST API). I don't understand why
the spec was changed retroactively and why Nova has been changed to
return X-OpenStack-Nova-API-Version instead of
X-OpenStack-Compute-API-Version HTTP headers [4].

To be blunt, Nova is the *implementation* of the OpenStack Compute
API. Ironic is the *implementation* of the OpenStack BareMetal API.

The HTTP headers should never have been changed like this, IMHO, and
I'm disappointed that they were. In fact, it looks like a very
select group of individuals pushed through this change [5] with
little to no input from the mailing list or community.

Since no support for these headers has yet to land in the client
packages, can we please reconsider this?

Thanks,
-jay


Hi Jay,

When I reviewed the changes in Ironic, that was one of the things I
noticed. I looked at the nova implementation at the time, and I saw
'nova' so even though I thought it should have been 'compute' (and
'baremetal' for Ironic), I thought it was OK to use 'ironic'. Sorry,
that was the wrong time for me to be a laamb ;)

I think we should deprecate and change to use 'baremetal' (if it isn't
going to be too painful).


Ruby, there's no reason to apologize. Nobody did anything intentionally 
bad or wrong, here :) I was just trying to bring the issue up and 
possibly change directions before too much time passed.


If anyone is to blame, it's me for not noticing the changes in the first 
place! :)


All the best,
-jay

__
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

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

[Jay Pipes]

On 06/15/2015 02:09 PM, Dmitry Tantsur wrote:



2015-06-15 19:50 GMT+02:00 Clint Byrum mailto:cl...@fewbar.com>>:

Excerpts from Jay Pipes's message of 2015-06-15 10:07:39 -0700:
> It has come to my attention in [1] that the microversion spec for Nova
> [2] and Ironic [3] have used the project name -- i.e. Nova and Ironic --
> instead of the name of the API -- i.e. "OpenStack Compute" and
> "OpenStack Bare Metal" -- in the HTTP header that a client passes to
> indicate a preference for or knowledge of a particular API microversion.
>
> The original spec said that the HTTP header should contain the name of
> the service type returned by the Keystone service catalog (which is also
> the official name of the REST API). I don't understand why the spec was
> changed retroactively and why Nova has been changed to return
> X-OpenStack-Nova-API-Version instead of X-OpenStack-Compute-API-Version
> HTTP headers [4].
>
> To be blunt, Nova is the *implementation* of the OpenStack Compute API.
> Ironic is the *implementation* of the OpenStack BareMetal API.
>
> The HTTP headers should never have been changed like this, IMHO, and I'm
> disappointed that they were. In fact, it looks like a very select group
> of individuals pushed through this change [5] with little to no input
> from the mailing list or community.
>
> Since no support for these headers has yet to land in the client
> packages, can we please reconsider this?

I tend to agree with you.

The juxtaposition is somewhat surprising. [1] Is cited as the reason for
making the change, but that governance change is addressing the way we
govern projects, not API's. The goal of the change itself is to
encourage
competition amongst projects. However, publishing an OpenStack API with
a project name anywhere in it is the opposite: it discourages
alternative
implementations. If we really believe there are no sacred cows and a
nova
replacement (or proxy, or accelerator, or or or..) could happen
inside the
OpenStack community, then we should be more careful about defining
the API


If Ironic will still be the main authority to define "the baremetal
API", header renaming won't help the alternative implementations.


IMHO, we need to start thinking of the public, versioned REST APIs as 
separate from both the implementation as well as the contributor 
community that develops the implementation.


Assuming the implementation == the REST API promotes the attitude that 
it doesn't really matter what the REST API looks like or how it evolves, 
since "the code is the documentation" and "the code is the API". This 
does a disservice to the user of the REST API, IMO.



Also, what to use for services, that do not have direct program mapping?
I.e., I'm planning to add microversioning to ironic-inspector. Who is
going to define a proper service name? Myself? The ironic team? Should I
bother the TC?


Does the ironic-inspector expose a REST API?

-jay


However, if we do believe that Nova and Ironic are special, then the API
can stand as-is, though I still find it sub-optimal.

I'm a little bit worried that we don't have a guiding principle to point
at somewhere. Perhaps the API WG can encode guidance either way ("We use
project names", or "we use service types").

[1] https://review.openstack.org/#/c/145740/

 >
 > Thanks,
 > -jay
 >
 > [1] https://review.openstack.org/#/c/187112/
 > [2]
 >

https://github.com/openstack/nova-specs/blob/master/specs/kilo/implemented/api-microversions.rst
 > [3]
 >

https://github.com/openstack/ironic-specs/blob/master/specs/kilo/api-microversions.rst
 > [4] https://review.openstack.org/#/c/155611/
 > [5] https://review.openstack.org/#/c/153183/
 >

__
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




--
--
-- Dmitry Tantsur
--


__
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

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

[Jay Pipes]

On 06/15/2015 03:45 PM, Kevin L. Mitchell wrote:

On Mon, 2015-06-15 at 13:07 -0400, Jay Pipes wrote:

The original spec said that the HTTP header should contain the name of
the service type returned by the Keystone service catalog (which is also
the official name of the REST API). I don't understand why the spec was
changed retroactively and why Nova has been changed to return
X-OpenStack-Nova-API-Version instead of X-OpenStack-Compute-API-Version
HTTP headers [4].


Given the disagreement evinced by the responses to this thread, let me
ask a question: Would there be any particular problem with using
"X-OpenStack-API-Version"?


I'd be cool with that. After all, you can't talk to two HTTP endpoints 
in the same HTTP request.


-jay

__
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

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

[Kevin L. Mitchell]

On Mon, 2015-06-15 at 13:07 -0400, Jay Pipes wrote:
> The original spec said that the HTTP header should contain the name of 
> the service type returned by the Keystone service catalog (which is also 
> the official name of the REST API). I don't understand why the spec was 
> changed retroactively and why Nova has been changed to return 
> X-OpenStack-Nova-API-Version instead of X-OpenStack-Compute-API-Version 
> HTTP headers [4].

Given the disagreement evinced by the responses to this thread, let me
ask a question: Would there be any particular problem with using
"X-OpenStack-API-Version"?
-- 
Kevin L. Mitchell 
Rackspace


__
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

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

[Ruby Loo]

On 15 June 2015 at 13:07, Jay Pipes  wrote:

> It has come to my attention in [1] that the microversion spec for Nova [2]
> and Ironic [3] have used the project name -- i.e. Nova and Ironic --
> instead of the name of the API -- i.e. "OpenStack Compute" and "OpenStack
> Bare Metal" -- in the HTTP header that a client passes to indicate a
> preference for or knowledge of a particular API microversion.
>
> The original spec said that the HTTP header should contain the name of the
> service type returned by the Keystone service catalog (which is also the
> official name of the REST API). I don't understand why the spec was changed
> retroactively and why Nova has been changed to return
> X-OpenStack-Nova-API-Version instead of X-OpenStack-Compute-API-Version
> HTTP headers [4].
>
> To be blunt, Nova is the *implementation* of the OpenStack Compute API.
> Ironic is the *implementation* of the OpenStack BareMetal API.
>
> The HTTP headers should never have been changed like this, IMHO, and I'm
> disappointed that they were. In fact, it looks like a very select group of
> individuals pushed through this change [5] with little to no input from the
> mailing list or community.
>
> Since no support for these headers has yet to land in the client packages,
> can we please reconsider this?
>
> Thanks,
> -jay
>
>
Hi Jay,

When I reviewed the changes in Ironic, that was one of the things I
noticed. I looked at the nova implementation at the time, and I saw 'nova'
so even though I thought it should have been 'compute' (and 'baremetal' for
Ironic), I thought it was OK to use 'ironic'. Sorry, that was the wrong
time for me to be a laamb ;)

I think we should deprecate and change to use 'baremetal' (if it isn't
going to be too painful).

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

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

[Chris Dent]

On Mon, 15 Jun 2015, Clint Byrum wrote:


I'm a little bit worried that we don't have a guiding principle to point
at somewhere. Perhaps the API WG can encode guidance either way ("We use
project names", or "we use service types").


I think it's a good idea to encode the principle, whatever it is,
but it feels like we are a rather long way from consensus on the
way to go.

There's a visible camp that would like to say that competing
projects should be competing over the effectiveness of their
implementation of a canonical (or even platonic) API.

In principle I have a lot of sympathy for this idea but it sort of begs
or presumes that the APIs that exist are:

* in the realm of or at least on their way to being "good enough"
* have some measure of stability
* should not themselves be overly subject to competitive forces

(at least two of these items are not true)

If that's the case, then we can imagine two different services both
of which implement the official compute API versions 2.blah to 3.foop
inclusive. That's probably an awful lot of work for everyone
involved?

Another way to look at things is that each project is seeking
knowledge about how to form a good API for a particular service but
nobody is quite there yet. In the meantime, if you use implementation X,
it's got microversions, please keep track.

And maybe someday microversion X of implementation Y will become
_the_ declared API for service Z? That could make a lot of people
feel like they've wasted effort.

I don't know where things are. Does anyone?

--
Chris Dent tw:@anticdent freenode:cdent
https://tank.peermore.com/tanks/cdent

__
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

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

[Dmitry Tantsur]

2015-06-15 19:50 GMT+02:00 Clint Byrum :

> Excerpts from Jay Pipes's message of 2015-06-15 10:07:39 -0700:
> > It has come to my attention in [1] that the microversion spec for Nova
> > [2] and Ironic [3] have used the project name -- i.e. Nova and Ironic --
> > instead of the name of the API -- i.e. "OpenStack Compute" and
> > "OpenStack Bare Metal" -- in the HTTP header that a client passes to
> > indicate a preference for or knowledge of a particular API microversion.
> >
> > The original spec said that the HTTP header should contain the name of
> > the service type returned by the Keystone service catalog (which is also
> > the official name of the REST API). I don't understand why the spec was
> > changed retroactively and why Nova has been changed to return
> > X-OpenStack-Nova-API-Version instead of X-OpenStack-Compute-API-Version
> > HTTP headers [4].
> >
> > To be blunt, Nova is the *implementation* of the OpenStack Compute API.
> > Ironic is the *implementation* of the OpenStack BareMetal API.
> >
> > The HTTP headers should never have been changed like this, IMHO, and I'm
> > disappointed that they were. In fact, it looks like a very select group
> > of individuals pushed through this change [5] with little to no input
> > from the mailing list or community.
> >
> > Since no support for these headers has yet to land in the client
> > packages, can we please reconsider this?
>
> I tend to agree with you.
>
> The juxtaposition is somewhat surprising. [1] Is cited as the reason for
> making the change, but that governance change is addressing the way we
> govern projects, not API's. The goal of the change itself is to encourage
> competition amongst projects. However, publishing an OpenStack API with
> a project name anywhere in it is the opposite: it discourages alternative
> implementations. If we really believe there are no sacred cows and a nova
> replacement (or proxy, or accelerator, or or or..) could happen inside the
> OpenStack community, then we should be more careful about defining the API
>

If Ironic will still be the main authority to define "the baremetal API",
header renaming won't help the alternative implementations.

Also, what to use for services, that do not have direct program mapping?
I.e., I'm planning to add microversioning to ironic-inspector. Who is going
to define a proper service name? Myself? The ironic team? Should I bother
the TC?


>
> However, if we do believe that Nova and Ironic are special, then the API
> can stand as-is, though I still find it sub-optimal.
>
> I'm a little bit worried that we don't have a guiding principle to point
> at somewhere. Perhaps the API WG can encode guidance either way ("We use
> project names", or "we use service types").
>
> [1] https://review.openstack.org/#/c/145740/
>
> >
> > Thanks,
> > -jay
> >
> > [1] https://review.openstack.org/#/c/187112/
> > [2]
> >
> https://github.com/openstack/nova-specs/blob/master/specs/kilo/implemented/api-microversions.rst
> > [3]
> >
> https://github.com/openstack/ironic-specs/blob/master/specs/kilo/api-microversions.rst
> > [4] https://review.openstack.org/#/c/155611/
> > [5] https://review.openstack.org/#/c/153183/
> >
>
> __
> 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
>



-- 
--
-- Dmitry Tantsur
--
__
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

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

[Clint Byrum]

Excerpts from Jay Pipes's message of 2015-06-15 10:07:39 -0700:
> It has come to my attention in [1] that the microversion spec for Nova 
> [2] and Ironic [3] have used the project name -- i.e. Nova and Ironic -- 
> instead of the name of the API -- i.e. "OpenStack Compute" and 
> "OpenStack Bare Metal" -- in the HTTP header that a client passes to 
> indicate a preference for or knowledge of a particular API microversion.
> 
> The original spec said that the HTTP header should contain the name of 
> the service type returned by the Keystone service catalog (which is also 
> the official name of the REST API). I don't understand why the spec was 
> changed retroactively and why Nova has been changed to return 
> X-OpenStack-Nova-API-Version instead of X-OpenStack-Compute-API-Version 
> HTTP headers [4].
> 
> To be blunt, Nova is the *implementation* of the OpenStack Compute API. 
> Ironic is the *implementation* of the OpenStack BareMetal API.
> 
> The HTTP headers should never have been changed like this, IMHO, and I'm 
> disappointed that they were. In fact, it looks like a very select group 
> of individuals pushed through this change [5] with little to no input 
> from the mailing list or community.
> 
> Since no support for these headers has yet to land in the client 
> packages, can we please reconsider this?

I tend to agree with you.

The juxtaposition is somewhat surprising. [1] Is cited as the reason for
making the change, but that governance change is addressing the way we
govern projects, not API's. The goal of the change itself is to encourage
competition amongst projects. However, publishing an OpenStack API with
a project name anywhere in it is the opposite: it discourages alternative
implementations. If we really believe there are no sacred cows and a nova
replacement (or proxy, or accelerator, or or or..) could happen inside the
OpenStack community, then we should be more careful about defining the API

However, if we do believe that Nova and Ironic are special, then the API
can stand as-is, though I still find it sub-optimal.

I'm a little bit worried that we don't have a guiding principle to point
at somewhere. Perhaps the API WG can encode guidance either way ("We use
project names", or "we use service types").

[1] https://review.openstack.org/#/c/145740/

> 
> Thanks,
> -jay
> 
> [1] https://review.openstack.org/#/c/187112/
> [2] 
> https://github.com/openstack/nova-specs/blob/master/specs/kilo/implemented/api-microversions.rst
> [3] 
> https://github.com/openstack/ironic-specs/blob/master/specs/kilo/api-microversions.rst
> [4] https://review.openstack.org/#/c/155611/
> [5] https://review.openstack.org/#/c/153183/
> 

__
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

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

[Sean Dague]

On 06/15/2015 01:07 PM, Jay Pipes wrote:
> It has come to my attention in [1] that the microversion spec for Nova
> [2] and Ironic [3] have used the project name -- i.e. Nova and Ironic --
> instead of the name of the API -- i.e. "OpenStack Compute" and
> "OpenStack Bare Metal" -- in the HTTP header that a client passes to
> indicate a preference for or knowledge of a particular API microversion.
> 
> The original spec said that the HTTP header should contain the name of
> the service type returned by the Keystone service catalog (which is also
> the official name of the REST API). I don't understand why the spec was
> changed retroactively and why Nova has been changed to return
> X-OpenStack-Nova-API-Version instead of X-OpenStack-Compute-API-Version
> HTTP headers [4].
> 
> To be blunt, Nova is the *implementation* of the OpenStack Compute API.
> Ironic is the *implementation* of the OpenStack BareMetal API.
> 
> The HTTP headers should never have been changed like this, IMHO, and I'm
> disappointed that they were. In fact, it looks like a very select group
> of individuals pushed through this change [5] with little to no input
> from the mailing list or community.
> 
> Since no support for these headers has yet to land in the client
> packages, can we please reconsider this?

I think you are seeing demons where there are none. I don't think it was
ever really clear in the specification that official project short
moniker was critical to the spec vs. code name that everyone uses. While
I didn't weigh in on the review in question, I wouldn't have really seen
an issue with it at the time.

Honestly, we should work through standardization of the service catalog
(as was discussed at Summit) first and before we push out a microversion
on these projects to change this header, especially as that is the hook
by which projects are versioning on now.

-Sean

-- 
Sean Dague
http://dague.net

__
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

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

[Jay Pipes]

On 06/15/2015 01:16 PM, Dmitry Tantsur wrote:

On 06/15/2015 07:07 PM, Jay Pipes wrote:

It has come to my attention in [1] that the microversion spec for Nova
[2] and Ironic [3] have used the project name -- i.e. Nova and Ironic --
instead of the name of the API -- i.e. "OpenStack Compute" and
"OpenStack Bare Metal" -- in the HTTP header that a client passes to
indicate a preference for or knowledge of a particular API microversion.

The original spec said that the HTTP header should contain the name of
the service type returned by the Keystone service catalog (which is also
the official name of the REST API). I don't understand why the spec was
changed retroactively and why Nova has been changed to return
X-OpenStack-Nova-API-Version instead of X-OpenStack-Compute-API-Version
HTTP headers [4].

To be blunt, Nova is the *implementation* of the OpenStack Compute API.
Ironic is the *implementation* of the OpenStack BareMetal API.

The HTTP headers should never have been changed like this, IMHO, and I'm
disappointed that they were. In fact, it looks like a very select group
of individuals pushed through this change [5] with little to no input
from the mailing list or community.

Since no support for these headers has yet to land in the client
packages, can we please reconsider this?


ironicclient has support for the header for a while, and anyway we
released it with Ironic Kilo, so I guess it's a breaking change.


Would it be possible to add support and deprecate the 
X-OpenStack-Ironic-API-Version HTTP header?



also while the only implementation and source of authority for the
"baremetal" API is Ironic, I'm not sure there's point of calling it
"baremetal API", but I'm neutral to this suggestion modulo compatibility
break.


What does the Ironic endpoint show up in the keystone service catalog as?

-jay


Thanks,
-jay

[1] https://review.openstack.org/#/c/187112/
[2]
https://github.com/openstack/nova-specs/blob/master/specs/kilo/implemented/api-microversions.rst


[3]
https://github.com/openstack/ironic-specs/blob/master/specs/kilo/api-microversions.rst


[4] https://review.openstack.org/#/c/155611/
[5] https://review.openstack.org/#/c/153183/

__

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


__
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

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

[Dmitry Tantsur]

On 06/15/2015 07:07 PM, Jay Pipes wrote:

It has come to my attention in [1] that the microversion spec for Nova
[2] and Ironic [3] have used the project name -- i.e. Nova and Ironic --
instead of the name of the API -- i.e. "OpenStack Compute" and
"OpenStack Bare Metal" -- in the HTTP header that a client passes to
indicate a preference for or knowledge of a particular API microversion.

The original spec said that the HTTP header should contain the name of
the service type returned by the Keystone service catalog (which is also
the official name of the REST API). I don't understand why the spec was
changed retroactively and why Nova has been changed to return
X-OpenStack-Nova-API-Version instead of X-OpenStack-Compute-API-Version
HTTP headers [4].

To be blunt, Nova is the *implementation* of the OpenStack Compute API.
Ironic is the *implementation* of the OpenStack BareMetal API.

The HTTP headers should never have been changed like this, IMHO, and I'm
disappointed that they were. In fact, it looks like a very select group
of individuals pushed through this change [5] with little to no input
from the mailing list or community.

Since no support for these headers has yet to land in the client
packages, can we please reconsider this?


ironicclient has support for the header for a while, and anyway we 
released it with Ironic Kilo, so I guess it's a breaking change.


also while the only implementation and source of authority for the 
"baremetal" API is Ironic, I'm not sure there's point of calling it 
"baremetal API", but I'm neutral to this suggestion modulo compatibility 
break.




Thanks,
-jay

[1] https://review.openstack.org/#/c/187112/
[2]
https://github.com/openstack/nova-specs/blob/master/specs/kilo/implemented/api-microversions.rst

[3]
https://github.com/openstack/ironic-specs/blob/master/specs/kilo/api-microversions.rst

[4] https://review.openstack.org/#/c/155611/
[5] https://review.openstack.org/#/c/153183/

__
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