<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Generator" content="Microsoft Word 15 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
        {font-family:宋体;
        panose-1:2 1 6 0 3 1 1 1 1 1;}
@font-face
        {font-family:"Cambria Math";
        panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
        {font-family:Calibri;
        panose-1:2 15 5 2 2 2 4 3 2 4;}
@font-face
        {font-family:"\@宋体";
        panose-1:2 1 6 0 3 1 1 1 1 1;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
        {margin:0cm;
        margin-bottom:.0001pt;
        font-size:12.0pt;
        font-family:宋体;}
a:link, span.MsoHyperlink
        {mso-style-priority:99;
        color:blue;
        text-decoration:underline;}
a:visited, span.MsoHyperlinkFollowed
        {mso-style-priority:99;
        color:purple;
        text-decoration:underline;}
p
        {mso-style-priority:99;
        mso-margin-top-alt:auto;
        margin-right:0cm;
        mso-margin-bottom-alt:auto;
        margin-left:0cm;
        font-size:12.0pt;
        font-family:宋体;}
span.EmailStyle18
        {mso-style-type:personal-reply;
        font-family:"Calibri",sans-serif;
        color:#1F497D;}
.MsoChpDefault
        {mso-style-type:export-only;
        font-family:"Calibri",sans-serif;}
@page WordSection1
        {size:612.0pt 792.0pt;
        margin:72.0pt 90.0pt 72.0pt 90.0pt;}
div.WordSection1
        {page:WordSection1;}
--></style><!--[if gte mso 9]><xml>
<o:shapedefaults v:ext="edit" spidmax="1026" />
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext="edit">
<o:idmap v:ext="edit" data="1" />
</o:shapelayout></xml><![endif]-->
</head>
<body lang="ZH-CN" link="blue" vlink="purple">
<div class="WordSection1">
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">I updated the Microversion specification in API-WG
<a href="https://review.openstack.org/187112">https://review.openstack.org/187112</a><o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">The new patchset adds min/max version headers as Ironic used:<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">X-Openstack-[PROJECT]-API-Minimum-Version<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">X-Openstack-[PROJECT]-API-Maximum-Version<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">And new response body for invalid version request.<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">  {<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">    "versionFault": {<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">      "max_version": "5.2",<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">      "min_version": "2.1",<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">      "description": "Version 5.3 is not supported by the API. \<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">          Minimum is 2.1 and maximum is 5.2."<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">    }<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">  }<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">Which for backward compatible can add the existed fields in the response also. For example, the nova response is<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">  {<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">    "versionFault": {<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">      "max_version": "5.2",<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">      "min_version": "2.1",<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">      "description": "Version 5.3 is not supported by the API. \<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">          Minimum is 2.1 and maximum is 5.2."<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">    },<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">    "computeFault": {<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">      "message": "Version 5.3 is not supported by the API. \<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">          Minimum is 2.1 and maximum is 5.2.",<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">      "code": 406<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">    }<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">  }<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">The “computeFault” fields is included by current implementation, we can still add here, hope deprecated in the future.<o:p></o:p></span></p>
<p class="MsoNormal"><a name="_MailEndCompose"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D"><o:p> </o:p></span></a></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">And the “experimental” flag in the X-OpenStack-Nova-API-Version header was deleted. It mentioned in the nova-spec but<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">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<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">“experimental” flag still usefull, we can propose separately.<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">Thanks<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D">Alex<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:10.5pt;font-family:"Calibri",sans-serif;color:#1F497D"><o:p> </o:p></span></p>
<div style="border:none;border-left:solid blue 1.5pt;padding:0cm 0cm 0cm 4.0pt">
<div>
<div style="border:none;border-top:solid #E1E1E1 1.0pt;padding:3.0pt 0cm 0cm 0cm">
<p class="MsoNormal"><b><span lang="EN-US" style="font-size:11.0pt;font-family:"Calibri",sans-serif">From:</span></b><span lang="EN-US" style="font-size:11.0pt;font-family:"Calibri",sans-serif"> Devananda van der Veen [mailto:devananda.vdv@gmail.com]
<br>
<b>Sent:</b> Monday, June 8, 2015 1:59 AM<br>
<b>To:</b> OpenStack Development Mailing List<br>
<b>Subject:</b> Re: [openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG<o:p></o:p></span></p>
</div>
</div>
<p class="MsoNormal"><span lang="EN-US"><o:p> </o:p></span></p>
<p><span lang="EN-US"><br>
On Jun 5, 2015 4:36 AM, "Sean Dague" <<a href="mailto:sean@dague.net">sean@dague.net</a>> wrote:<br>
><br>
> On 06/05/2015 01:28 AM, Adrian Otto wrote:<br>
> ><br>
> >> On Jun 4, 2015, at 11:03 AM, Devananda van der Veen<br>
> >> <<a href="mailto:devananda.vdv@gmail.com">devananda.vdv@gmail.com</a> <mailto:<a href="mailto:devananda.vdv@gmail.com">devananda.vdv@gmail.com</a>>> wrote:<br>
> >><br>
> >><br>
> >> On Jun 4, 2015 12:00 AM, "Xu, Hejie" <<a href="mailto:hejie.xu@intel.com">hejie.xu@intel.com</a><br>
> >> <mailto:<a href="mailto:hejie.xu@intel.com">hejie.xu@intel.com</a>>> wrote:<br>
> >> ><br>
> >> > Hi, guys,<br>
> >> ><br>
> >> > I’m working on adding Microversion into the API-WG’s guideline which<br>
> >> make sure we have consistent Microversion behavior in the API for user.<br>
> >> > The Nova and Ironic already have Microversion implementation, and as<br>
> >> I know Magnum <a href="https://review.openstack.org/#/c/184975/">https://review.openstack.org/#/c/184975/</a> is going to<br>
> >> implement Microversion also.<br>
> >> ><br>
> >> > Hope all the projects which support( or plan to) Microversion can<br>
> >> join the review of guideline.<br>
> >> ><br>
> >> > The Mircoversion specification(this almost copy from nova-specs):<br>
> >> <a href="https://review.openstack.org/#/c/187112">https://review.openstack.org/#/c/187112</a><br>
> >> > And another guideline for when we should bump Mircoversion<br>
> >> <a href="https://review.openstack.org/#/c/187896/">https://review.openstack.org/#/c/187896/</a><br>
> >> ><br>
> >> > As I know, there already have a little different between Nova and<br>
> >> Ironic’s implementation. Ironic return min/max version when the requested<br>
> >> > version doesn’t support in server by http-headers. There isn’t such<br>
> >> thing in nova. But that is something for version negotiation we need<br>
> >> for nova also.<br>
> >> > Sean have pointed out we should use response body instead of http<br>
> >> headers, the body can includes error message. Really hope ironic team<br>
> >> can take a<br>
> >> > look at if you guys have compelling reason for using http headers.<br>
> >> ><br>
> >> > And if we think return body instead of http headers, we probably<br>
> >> need think about back-compatible also. Because Microversion itself<br>
> >> isn’t versioned.<br>
> >> > So I think we should keep those header for a while, does make sense?<br>
> >> ><br>
> >> > Hope we have good guideline for Microversion, because we only can<br>
> >> change Mircoversion itself by back-compatible way.<br>
> >><br>
> >> Ironic returns the min/max/current API version in the http headers for<br>
> >> every request.<br>
> >><br>
> >> Why would it return this information in a header on success and in the<br>
> >> body on failure? (How would this inconsistency benefit users?)<br>
> >><br>
> >> To be clear, I'm not opposed to *also* having a useful error message<br>
> >> in the body, but while writing the client side of api versioning,<br>
> >> parsing the range consistently from the response header is, IMO,<br>
> >> better than requiring a conditional.<br>
> >><br>
> > +1. I fully agree with Devananda on this point. Use the headers<br>
> > consistently, and add helpful errors into the body only as an addition<br>
> > to that behavior, not a substitute.<br>
><br>
> I think the difference between Nova and Ironic here is that Nova doesn't<br>
> send all the headers all the time in the final implementation (that part<br>
> of the spec evolved out I think). Part of that was pressure about Header<br>
> bloat that people were concerned about, as that impacts caching layers.<br>
><br>
> I would a agree that if Ironic is sending all the headers all the time,<br>
> that's fine. However, for consistency it would be great to also put a<br>
> real body that explains the issue as well, <o:p></o:p></span></p>
<p><span lang="EN-US">Agreed.<o:p></o:p></span></p>
<p><span lang="EN-US">> as headers are not the first<br>
> place people look when things go wrong, and are often not logged by<br>
> client side tools on errors (where the body would be).<br>
><br>
>         -Sean<br>
><br>
> --<br>
> Sean Dague<br>
> <a href="http://dague.net">http://dague.net</a><br>
><br>
> __________________________________________________________________________<br>
> OpenStack Development Mailing List (not for usage questions)<br>
> Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe">
OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><o:p></o:p></span></p>
</div>
</div>
</body>
</html>