Open Stack

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": {
      "max_version": "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": {
      "max_version": "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 at 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 at dague.net<mailto:sean at 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 at gmail.com<mailto:devananda.vdv at gmail.com> <mailto: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>
> >> <mailto: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,

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 at lists.openstack.org?subject:unsubscribe<http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe>
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150610/d2c85dc7/attachment.html>