Just want to add that for logging purposes, consistency, as Devananda explains and Adrian and Sean agree, is really important. The number of fields in a header response should be consistent. If the field is not always used, a placeholder should be put in (usually a “-“ in logs). Makes parsing these things much easier.
Thanks for both consistency and for specific instance related info in the message bodies. The operators also appreciate this. --Rocky From: Xu, Hejie [mailto:hejie...@intel.com] Sent: Thursday, June 11, 2015 02:10 To: OpenStack Development Mailing List (not for usage questions) Subject: Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG Salvatore, thanks for the info, will try to review as soon as possible. Hope we get consistent implementation. From: Salvatore Orlando [mailto:sorla...@nicira.com] Sent: Wednesday, June 10, 2015 4:51 PM To: OpenStack Development Mailing List (not for usage questions) Subject: Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG As a further data point, Neutron has been trying to introduce microversioning for a while, without success so far. Given the sheer amount of backends the management layer integrates with, and the constant need for the various subteams to "experiment" with the API, the proposal [1] has probably some differences with the proposed guideline. Since the proposal is not yet approved nor implemented, perhaps it would be worth looking at those differences, and get your advice on whether it might be better if neutron adheres to the current guideline proposal or whether it might be the case to include Neutron's requirements in the current guideline proposal. Salvatore [1] https://review.openstack.org/#/c/136760/ On 10 June 2015 at 06:28, Xu, Hejie <hejie...@intel.com<mailto:hejie...@intel.com>> wrote: 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....@gmail.com<mailto:devananda....@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" <s...@dague.net<mailto:s...@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....@gmail.com<mailto:devananda....@gmail.com> > >> <mailto:devananda....@gmail.com<mailto:devananda....@gmail.com>>> wrote: > >> > >> > >> On Jun 4, 2015 12:00 AM, "Xu, Hejie" > >> <hejie...@intel.com<mailto:hejie...@intel.com> > >> <mailto:hejie...@intel.com<mailto:hejie...@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-requ...@lists.openstack.org?subject:unsubscribe<http://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://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
