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

Sean Dague sean at dague.net
Fri Jun 5 11:35:28 UTC 2015

On 06/05/2015 01:28 AM, Adrian Otto wrote:
>> On Jun 4, 2015, at 11:03 AM, Devananda van der Veen
>> <devananda.vdv at gmail.com <mailto:devananda.vdv at gmail.com>> wrote:
>> On Jun 4, 2015 12:00 AM, "Xu, Hejie" <hejie.xu at intel.com
>> <mailto:hejie.xu at 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 Dague

More information about the OpenStack-dev mailing list