settingsLogin | Registersettings

[openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG

0 votes

Hi, guys,

I'm working on adding Microversion into the API-WG's guideline which make sure we have consistent Microversion behavior in the API for user.
The Nova and Ironic already have Microversion implementation, and as I know Magnum https://review.openstack.org/#/c/184975/ is going to implement Microversion also.

Hope all the projects which support( or plan to) Microversion can join the review of guideline.

The Mircoversion specification(this almost copy from nova-specs): https://review.openstack.org/#/c/187112
And another guideline for when we should bump Mircoversion https://review.openstack.org/#/c/187896/

As I know, there already have a little different between Nova and Ironic's implementation. Ironic return min/max version when the requested
version doesn't support in server by http-headers. There isn't such thing in nova. But that is something for version negotiation we need for nova also.
Sean have pointed out we should use response body instead of http headers, the body can includes error message. Really hope ironic team can take a
look at if you guys have compelling reason for using http headers.

And if we think return body instead of http headers, we probably need think about back-compatible also. Because Microversion itself isn't versioned.
So I think we should keep those header for a while, does make sense?

Hope we have good guideline for Microversion, because we only can change Mircoversion itself by back-compatible way.

Thanks
Alex Xu


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
asked Jun 4, 2015 in openstack-dev by Xu,_Hejie (1,160 points)   2

45 Responses

0 votes

Hi Alex,

Based on my understanding, the Mangum code base is get from Ironic, that's
why Magnum using http headers because when Magnum was created, Ironic is
also using http headers.

Perhaps Magnum can follow the way how Ironic move to use Microversion?

Thanks.

2015-06-04 14:58 GMT+08:00 Xu, Hejie hejie.xu@intel.com:

Hi, guys,

I’m working on adding Microversion into the API-WG’s guideline which make
sure we have consistent Microversion behavior in the API for user.
The Nova and Ironic already have Microversion implementation, and as I
know Magnum *https://review.openstack.org/#/c/184975/*
https://review.openstack.org/#/c/184975/ is going to implement
Microversion also.

Hope all the projects which support( or plan to) Microversion can join the
review of guideline.

The Mircoversion specification(this almost copy from nova-specs):
*https://review.openstack.org/#/c/187112*
https://review.openstack.org/#/c/187112
And another guideline for when we should bump Mircoversion
*https://review.openstack.org/#/c/187896/*
https://review.openstack.org/#/c/187896/

As I know, there already have a little different between Nova and Ironic’s
implementation. Ironic return min/max version when the requested
version doesn’t support in server by http-headers. There isn’t such thing
in nova. But that is something for version negotiation we need for nova
also.
Sean have pointed out we should use response body instead of http headers,
the body can includes error message. Really hope ironic team can take a
look at if you guys have compelling reason for using http headers.

And if we think return body instead of http headers, we probably need
think about back-compatible also. Because Microversion itself isn’t
versioned.
So I think we should keep those header for a while, does make sense?

Hope we have good guideline for Microversion, because we only can change
Mircoversion itself by back-compatible way.

Thanks
Alex Xu


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

--
Thanks,

Jay Lau (Guangya Liu)


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Jun 4, 2015 by Jay_Lau (7,320 points)   1 8 10
0 votes

On 4 June 2015 at 02:58, Xu, Hejie hejie.xu@intel.com wrote:

...
And another guideline for when we should bump Mircoversion
*https://review.openstack.org/#/c/187896/*
https://review.openstack.org/#/c/187896/

This is timely because just this very minute I was going to send out email
to the Ironic community about this -- when should we bump the
microversion. For fear of hijacking this thread, I'm going to start a new
thread to discuss with Ironic folks first.

As I know, there already have a little different between Nova and Ironic’s
implementation. Ironic return min/max version when the requested
version doesn’t support in server by http-headers. There isn’t such thing
in nova. But that is something for version negotiation we need for nova
also.
Sean have pointed out we should use response body instead of http headers,
the body can includes error message. Really hope ironic team can take a
look at if you guys have compelling reason for using http headers.

I don't want to change the ironic code so let's go with http headers.
(That's a good enough reason, isn't it?) :-)

By the way, did you see Ironic's spec on the/our desired behaviour between
Ironic's server and client [1]? It's ... .

Thanks Alex!

--ruby

[1]
http://specs.openstack.org/openstack/ironic-specs/specs/kilo/api-microversions.html


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Jun 4, 2015 by Ruby_Loo (4,000 points)   2 3
0 votes

On Jun 4, 2015 12:00 AM, "Xu, Hejie" hejie.xu@intel.com wrote:

Hi, guys,

I’m working on adding Microversion into the API-WG’s guideline which make
sure we have consistent Microversion behavior in the API for user.
The Nova and Ironic already have Microversion implementation, and as I
know Magnum https://review.openstack.org/#/c/184975/ is going to implement
Microversion also.

Hope all the projects which support( or plan to) Microversion can join
the review of guideline.

The Mircoversion specification(this almost copy from nova-specs):
https://review.openstack.org/#/c/187112
And another guideline for when we should bump Mircoversion
https://review.openstack.org/#/c/187896/

As I know, there already have a little different between Nova and
Ironic’s implementation. Ironic return min/max version when the requested
version doesn’t support in server by http-headers. There isn’t such thing
in nova. But that is something for version negotiation we need for nova
also.
Sean have pointed out we should use response body instead of http
headers, the body can includes error message. Really hope ironic team can
take a
look at if you guys have compelling reason for using http headers.

And if we think return body instead of http headers, we probably need
think about back-compatible also. Because Microversion itself isn’t
versioned.
So I think we should keep those header for a while, does make sense?

Hope we have good guideline for Microversion, because we only can change
Mircoversion itself by back-compatible way.

Ironic returns the min/max/current API version in the http headers for
every request.

Why would it return this information in a header on success and in the body
on failure? (How would this inconsistency benefit users?)

To be clear, I'm not opposed to also having a useful error message in the
body, but while writing the client side of api versioning, parsing the
range consistently from the response header is, IMO, better than requiring
a conditional.

-Deva


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Jun 4, 2015 by Devananda_van_der_Ve (10,380 points)   2 3 5
0 votes

On Jun 4, 2015, at 11:03 AM, Devananda van der Veen devananda.vdv@gmail.com wrote:

On Jun 4, 2015 12:00 AM, "Xu, Hejie" hejie.xu@intel.com wrote:

Hi, guys,

I’m working on adding Microversion into the API-WG’s guideline which make sure we have consistent Microversion behavior in the API for user.
The Nova and Ironic already have Microversion implementation, and as I know Magnum https://review.openstack.org/#/c/184975/ is going to implement Microversion also.

Hope all the projects which support( or plan to) Microversion can join the review of guideline.

The Mircoversion specification(this almost copy from nova-specs): https://review.openstack.org/#/c/187112
And another guideline for when we should bump Mircoversion https://review.openstack.org/#/c/187896/

As I know, there already have a little different between Nova and Ironic’s implementation. Ironic return min/max version when the requested
version doesn’t support in server by http-headers. There isn’t such thing in nova. But that is something for version negotiation we need for nova also.
Sean have pointed out we should use response body instead of http headers, the body can includes error message. Really hope ironic team can take a
look at if you guys have compelling reason for using http headers.

And if we think return body instead of http headers, we probably need think about back-compatible also. Because Microversion itself isn’t versioned.
So I think we should keep those header for a while, does make sense?

Hope we have good guideline for Microversion, because we only can change Mircoversion itself by back-compatible way.

Ironic returns the min/max/current API version in the http headers for every request.

Why would it return this information in a header on success and in the body on failure? (How would this inconsistency benefit users?)

To be clear, I'm not opposed to also having a useful error message in the body, but while writing the client side of api versioning, parsing the range consistently from the response header is, IMO, better than requiring a conditional.

+1. I fully agree with Devananda on this point. Use the headers consistently, and add helpful errors into the body only as an addition to that behavior, not a substitute.

Adrian

-Deva


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


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Jun 5, 2015 by Adrian_Otto (11,060 points)   2 3 6
0 votes

Hi, Jay, I would say follow what happened on this guideline https://review.openstack.org/#/c/187112 :)

From: Jay Lau [mailto:jay.lau.513@gmail.com]
Sent: Thursday, June 4, 2015 5:41 PM
To: OpenStack Development Mailing List (not for usage questions)
Subject: Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG

Hi Alex,

Based on my understanding, the Mangum code base is get from Ironic, that's why Magnum using http headers because when Magnum was created, Ironic is also using http headers.
Perhaps Magnum can follow the way how Ironic move to use Microversion?
Thanks.

2015-06-04 14:58 GMT+08:00 Xu, Hejie hejie.xu@intel.com:
Hi, guys,

I’m working on adding Microversion into the API-WG’s guideline which make sure we have consistent Microversion behavior in the API for user.
The Nova and Ironic already have Microversion implementation, and as I know Magnum https://review.openstack.org/#/c/184975/ is going to implement Microversion also.

Hope all the projects which support( or plan to) Microversion can join the review of guideline.

The Mircoversion specification(this almost copy from nova-specs): https://review.openstack.org/#/c/187112
And another guideline for when we should bump Mircoversion https://review.openstack.org/#/c/187896/

As I know, there already have a little different between Nova and Ironic’s implementation. Ironic return min/max version when the requested
version doesn’t support in server by http-headers. There isn’t such thing in nova. But that is something for version negotiation we need for nova also.
Sean have pointed out we should use response body instead of http headers, the body can includes error message. Really hope ironic team can take a
look at if you guys have compelling reason for using http headers.

And if we think return body instead of http headers, we probably need think about back-compatible also. Because Microversion itself isn’t versioned.
So I think we should keep those header for a while, does make sense?

Hope we have good guideline for Microversion, because we only can change Mircoversion itself by back-compatible way.

Thanks
Alex Xu


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

--
Thanks,
Jay Lau (Guangya Liu)


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Jun 5, 2015 by Xu,_Hejie (1,160 points)   2
0 votes

On 06/05/2015 01:28 AM, Adrian Otto wrote:

On Jun 4, 2015, at 11:03 AM, Devananda van der Veen
<devananda.vdv@gmail.com devananda.vdv@gmail.com> wrote:

On Jun 4, 2015 12:00 AM, "Xu, Hejie" <hejie.xu@intel.com
hejie.xu@intel.com> wrote:

Hi, guys,

I’m working on adding Microversion into the API-WG’s guideline which
make sure we have consistent Microversion behavior in the API for user.
The Nova and Ironic already have Microversion implementation, and as
I know Magnum https://review.openstack.org/#/c/184975/ is going to
implement Microversion also.

Hope all the projects which support( or plan to) Microversion can
join the review of guideline.

The Mircoversion specification(this almost copy from nova-specs):
https://review.openstack.org/#/c/187112
And another guideline for when we should bump Mircoversion
https://review.openstack.org/#/c/187896/

As I know, there already have a little different between Nova and
Ironic’s implementation. Ironic return min/max version when the requested
version doesn’t support in server by http-headers. There isn’t such
thing in nova. But that is something for version negotiation we need
for nova also.
Sean have pointed out we should use response body instead of http
headers, the body can includes error message. Really hope ironic team
can take a
look at if you guys have compelling reason for using http headers.

And if we think return body instead of http headers, we probably
need think about back-compatible also. Because Microversion itself
isn’t versioned.
So I think we should keep those header for a while, does make sense?

Hope we have good guideline for Microversion, because we only can
change Mircoversion itself by back-compatible way.

Ironic returns the min/max/current API version in the http headers for
every request.

Why would it return this information in a header on success and in the
body on failure? (How would this inconsistency benefit users?)

To be clear, I'm not opposed to also having a useful error message
in the body, but while writing the client side of api versioning,
parsing the range consistently from the response header is, IMO,
better than requiring a conditional.

+1. I fully agree with Devananda on this point. Use the headers
consistently, and add helpful errors into the body only as an addition
to that behavior, not a substitute.

I think the difference between Nova and Ironic here is that Nova doesn't
send all the headers all the time in the final implementation (that part
of the spec evolved out I think). Part of that was pressure about Header
bloat that people were concerned about, as that impacts caching layers.

I would a agree that if Ironic is sending all the headers all the time,
that's fine. However, for consistency it would be great to also put a
real body that explains the issue as well, as headers are not the first
place people look when things go wrong, and are often not logged by
client side tools on errors (where the body would be).

-Sean

--
Sean Dague
http://dague.net


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Jun 5, 2015 by Sean_Dague (66,200 points)   4 8 14
0 votes

2015-06-04 22:23 GMT+08:00 Ruby Loo rlooyahoo@gmail.com:

On 4 June 2015 at 02:58, Xu, Hejie hejie.xu@intel.com wrote:

...
And another guideline for when we should bump Mircoversion
*https://review.openstack.org/#/c/187896/*
https://review.openstack.org/#/c/187896/

This is timely because just this very minute I was going to send out email
to the Ironic community about this -- when should we bump the
microversion. For fear of hijacking this thread, I'm going to start a new
thread to discuss with Ironic folks first.

Thanks Ruby

As I know, there already have a little different between Nova and
Ironic’s implementation. Ironic return min/max version when the requested
version doesn’t support in server by http-headers. There isn’t such thing
in nova. But that is something for version negotiation we need for nova
also.
Sean have pointed out we should use response body instead of http
headers, the body can includes error message. Really hope ironic team can
take a
look at if you guys have compelling reason for using http headers.

I don't want to change the ironic code so let's go with http headers.
(That's a good enough reason, isn't it?) :-)

So I translate to we want to back-compatible.

By the way, did you see Ironic's spec on the/our desired behaviour between
Ironic's server and client [1]? It's ... .

Emm... It's... great! Good news is there isn't big different between nova
and ironic.

Thanks Alex!

--ruby

[1]
http://specs.openstack.org/openstack/ironic-specs/specs/kilo/api-microversions.html


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


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Jun 7, 2015 by Alex_Xu (8,960 points)   1 3 3
0 votes

2015-06-05 19:35 GMT+08:00 Sean Dague sean@dague.net:

On 06/05/2015 01:28 AM, Adrian Otto wrote:

On Jun 4, 2015, at 11:03 AM, Devananda van der Veen
<devananda.vdv@gmail.com devananda.vdv@gmail.com> wrote:

On Jun 4, 2015 12:00 AM, "Xu, Hejie" <hejie.xu@intel.com
hejie.xu@intel.com> wrote:

Hi, guys,

I’m working on adding Microversion into the API-WG’s guideline which
make sure we have consistent Microversion behavior in the API for user.
The Nova and Ironic already have Microversion implementation, and as
I know Magnum https://review.openstack.org/#/c/184975/ is going to
implement Microversion also.

Hope all the projects which support( or plan to) Microversion can
join the review of guideline.

The Mircoversion specification(this almost copy from nova-specs):
https://review.openstack.org/#/c/187112
And another guideline for when we should bump Mircoversion
https://review.openstack.org/#/c/187896/

As I know, there already have a little different between Nova and
Ironic’s implementation. Ironic return min/max version when the
requested
version doesn’t support in server by http-headers. There isn’t such
thing in nova. But that is something for version negotiation we need
for nova also.
Sean have pointed out we should use response body instead of http
headers, the body can includes error message. Really hope ironic team
can take a
look at if you guys have compelling reason for using http headers.

And if we think return body instead of http headers, we probably
need think about back-compatible also. Because Microversion itself
isn’t versioned.
So I think we should keep those header for a while, does make sense?

Hope we have good guideline for Microversion, because we only can
change Mircoversion itself by back-compatible way.

Ironic returns the min/max/current API version in the http headers for
every request.

Why would it return this information in a header on success and in the
body on failure? (How would this inconsistency benefit users?)

To be clear, I'm not opposed to also having a useful error message
in the body, but while writing the client side of api versioning,
parsing the range consistently from the response header is, IMO,
better than requiring a conditional.

+1. I fully agree with Devananda on this point. Use the headers
consistently, and add helpful errors into the body only as an addition
to that behavior, not a substitute.

I think the difference between Nova and Ironic here is that Nova doesn't
send all the headers all the time in the final implementation (that part
of the spec evolved out I think). Part of that was pressure about Header
bloat that people were concerned about, as that impacts caching layers.

Can I ask more detail about this concern? Header bloat may have performance
problem for extra data transfer between server and client. For the caching,
we use Vary header. What impact you refer to?

I would a agree that if Ironic is sending all the headers all the time,
that's fine. However, for consistency it would be great to also put a
real body that explains the issue as well, as headers are not the first
place people look when things go wrong, and are often not logged by
client side tools on errors (where the body would be).

Thanks all the replied, let me update the guideline.

    -Sean

--
Sean Dague
http://dague.net


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


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Jun 7, 2015 by Alex_Xu (8,960 points)   1 3 3
0 votes

On Jun 5, 2015 4:36 AM, "Sean Dague" sean@dague.net wrote:

On 06/05/2015 01:28 AM, Adrian Otto wrote:

On Jun 4, 2015, at 11:03 AM, Devananda van der Veen
<devananda.vdv@gmail.com devananda.vdv@gmail.com> wrote:

On Jun 4, 2015 12:00 AM, "Xu, Hejie" <hejie.xu@intel.com
hejie.xu@intel.com> wrote:

Hi, guys,

I’m working on adding Microversion into the API-WG’s guideline which
make sure we have consistent Microversion behavior in the API for user.
The Nova and Ironic already have Microversion implementation, and as
I know Magnum https://review.openstack.org/#/c/184975/ is going to
implement Microversion also.

Hope all the projects which support( or plan to) Microversion can
join the review of guideline.

The Mircoversion specification(this almost copy from nova-specs):
https://review.openstack.org/#/c/187112
And another guideline for when we should bump Mircoversion
https://review.openstack.org/#/c/187896/

As I know, there already have a little different between Nova and
Ironic’s implementation. Ironic return min/max version when the
requested
version doesn’t support in server by http-headers. There isn’t such
thing in nova. But that is something for version negotiation we need
for nova also.
Sean have pointed out we should use response body instead of http
headers, the body can includes error message. Really hope ironic team
can take a
look at if you guys have compelling reason for using http headers.

And if we think return body instead of http headers, we probably
need think about back-compatible also. Because Microversion itself
isn’t versioned.
So I think we should keep those header for a while, does make sense?

Hope we have good guideline for Microversion, because we only can
change Mircoversion itself by back-compatible way.

Ironic returns the min/max/current API version in the http headers for
every request.

Why would it return this information in a header on success and in the
body on failure? (How would this inconsistency benefit users?)

To be clear, I'm not opposed to also having a useful error message
in the body, but while writing the client side of api versioning,
parsing the range consistently from the response header is, IMO,
better than requiring a conditional.

+1. I fully agree with Devananda on this point. Use the headers
consistently, and add helpful errors into the body only as an addition
to that behavior, not a substitute.

I think the difference between Nova and Ironic here is that Nova doesn't
send all the headers all the time in the final implementation (that part
of the spec evolved out I think). Part of that was pressure about Header
bloat that people were concerned about, as that impacts caching layers.

I would a agree that if Ironic is sending all the headers all the time,
that's fine. However, for consistency it would be great to also put a
real body that explains the issue as well,

Agreed.

as headers are not the first
place people look when things go wrong, and are often not logged by
client side tools on errors (where the body would be).

    -Sean

--
Sean Dague
http://dague.net


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

OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Jun 7, 2015 by Devananda_van_der_Ve (10,380 points)   2 3 5
0 votes

I updated the Microversion specification in API-WG https://review.openstack.org/187112

The new patchset adds min/max version headers as Ironic used:
X-Openstack-[PROJECT]-API-Minimum-Version
X-Openstack-[PROJECT]-API-Maximum-Version

And new response body for invalid version request.

{
"versionFault": {
"maxversion": "5.2",
"min
version": "2.1",
"description": "Version 5.3 is not supported by the API. \
Minimum is 2.1 and maximum is 5.2."
}
}

Which for backward compatible can add the existed fields in the response also. For example, the nova response is

{
"versionFault": {
"maxversion": "5.2",
"min
version": "2.1",
"description": "Version 5.3 is not supported by the API. \
Minimum is 2.1 and maximum is 5.2."
},
"computeFault": {
"message": "Version 5.3 is not supported by the API. \
Minimum is 2.1 and maximum is 5.2.",
"code": 406
}
}

The “computeFault” fields is included by current implementation, we can still add here, hope deprecated in the future.

And the “experimental” flag in the X-OpenStack-Nova-API-Version header was deleted. It mentioned in the nova-spec but
It didn’t implement. And I didn’t saw the same thing in the ironic. For current all the things satisfied all the cases. If we
“experimental” flag still usefull, we can propose separately.

Thanks
Alex

From: Devananda van der Veen [mailto:devananda.vdv@gmail.com]
Sent: Monday, June 8, 2015 1:59 AM
To: OpenStack Development Mailing List
Subject: Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG

On Jun 5, 2015 4:36 AM, "Sean Dague" sean@dague.net wrote:

On 06/05/2015 01:28 AM, Adrian Otto wrote:

On Jun 4, 2015, at 11:03 AM, Devananda van der Veen
<devananda.vdv@gmail.com devananda.vdv@gmail.com> wrote:

On Jun 4, 2015 12:00 AM, "Xu, Hejie" <hejie.xu@intel.com
hejie.xu@intel.com> wrote:

Hi, guys,

I’m working on adding Microversion into the API-WG’s guideline which
make sure we have consistent Microversion behavior in the API for user.
The Nova and Ironic already have Microversion implementation, and as
I know Magnum https://review.openstack.org/#/c/184975/ is going to
implement Microversion also.

Hope all the projects which support( or plan to) Microversion can
join the review of guideline.

The Mircoversion specification(this almost copy from nova-specs):
https://review.openstack.org/#/c/187112
And another guideline for when we should bump Mircoversion
https://review.openstack.org/#/c/187896/

As I know, there already have a little different between Nova and
Ironic’s implementation. Ironic return min/max version when the requested
version doesn’t support in server by http-headers. There isn’t such
thing in nova. But that is something for version negotiation we need
for nova also.
Sean have pointed out we should use response body instead of http
headers, the body can includes error message. Really hope ironic team
can take a
look at if you guys have compelling reason for using http headers.

And if we think return body instead of http headers, we probably
need think about back-compatible also. Because Microversion itself
isn’t versioned.
So I think we should keep those header for a while, does make sense?

Hope we have good guideline for Microversion, because we only can
change Mircoversion itself by back-compatible way.

Ironic returns the min/max/current API version in the http headers for
every request.

Why would it return this information in a header on success and in the
body on failure? (How would this inconsistency benefit users?)

To be clear, I'm not opposed to also having a useful error message
in the body, but while writing the client side of api versioning,
parsing the range consistently from the response header is, IMO,
better than requiring a conditional.

+1. I fully agree with Devananda on this point. Use the headers
consistently, and add helpful errors into the body only as an addition
to that behavior, not a substitute.

I think the difference between Nova and Ironic here is that Nova doesn't
send all the headers all the time in the final implementation (that part
of the spec evolved out I think). Part of that was pressure about Header
bloat that people were concerned about, as that impacts caching layers.

I would a agree that if Ironic is sending all the headers all the time,
that's fine. However, for consistency it would be great to also put a
real body that explains the issue as well,

Agreed.

as headers are not the first
place people look when things go wrong, and are often not logged by
client side tools on errors (where the body would be).

    -Sean

--
Sean Dague
http://dague.net


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

OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Jun 10, 2015 by Xu,_Hejie (1,160 points)   2
...