<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Tue, Apr 29, 2014 at 7:01 AM, Sean Dague <span dir="ltr"><<a href="mailto:sean@dague.net" target="_blank">sean@dague.net</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div class="HOEnZb"><div class="h5">On 04/28/2014 02:06 PM, David Kranz wrote:<br>
> On 04/27/2014 10:02 PM, Matthew Treinish wrote:<br>
>> On Mon, Apr 28, 2014 at 01:01:00AM +0000, Kenichi Oomichi wrote:<br>
>>> Hi,<br>
>>><br>
>>> Sorry for my late response, but I'd like to discuss this again.<br>
>>><br>
>>> Now we are working for adding Nova API responses checks to Tempest[1] to<br>
>>> block backward incompatible changes.<br>
>>> With this work, Tempest checks each response(status code, response body)<br>
>>> and raises a test failure exception if detecting something unexpected.<br>
>>> For example if some API parameter, which is defined as 'required'<br>
>>> Tempest<br>
>>> side, does not exist in response body, Tempest test fails.<br>
>>><br>
>>> We are defining API parameters as 'required' if they are not API<br>
>>> extensions<br>
>>> or they are not depended on Nova configuration. In addition now Tempest<br>
>>> allows additional API parameters, that means Tempest does not fail<br>
>>> even if<br>
>>> Nova response includes unexpected API parameters. Because I think the<br>
>>> removal<br>
>>> of API parameter causes backward incompatible issue but the addition<br>
>>> does not<br>
>>> cause it.<br>
>> So, AIUI we can only add parameters to an API with a new extension.<br>
>> The API<br>
>> change guidelines also say that adding new properties must be<br>
>> conditional:<br>
>><br>
>> <a href="https://wiki.openstack.org/wiki/APIChangeGuidelines#Generally_Considered_OK" target="_blank">https://wiki.openstack.org/wiki/APIChangeGuidelines#Generally_Considered_OK</a><br>
>><br>
> I just wanted to note that the original referenced wiki page, assembled<br>
> by markmc and myself, did not specify the need for an extension in order<br>
> to add a value to a return dict or add a value to a dict argument if the<br>
> existing api would ignore it. This was changed (and honestly I did not<br>
> notice this change at the time) last August to require an extension:<br>
> <a href="https://wiki.openstack.org/w/index.php?title=APIChangeGuidelines&diff=prev&oldid=28593" target="_blank">https://wiki.openstack.org/w/index.php?title=APIChangeGuidelines&diff=prev&oldid=28593</a>.<br>

><br>
> Is there any trace left of discussions around that change?<br>
><br>
> The original wording allowed the api to evolve as long as a "reasonable"<br>
> application would not be broken. Essentially the extra value becomes<br>
> optional and new client or server code can check for it. The new<br>
> definition is quite strict and similar to what leads to many Windows<br>
> APIs having names like CreateWindowEx. Not saying being strict is bad,<br>
> but it will require a lot of changes to the client libraries as well as<br>
> tempest because there are a lot of extensions that are not checked by<br>
> either.<br>
<br>
</div></div>If I remember correctly that arose out of Portland summit sessions.<br>
Basically you need to provide some signaling to the client on what they<br>
should expect. And this kind of organically grew into that.<br>
<br></blockquote><div><br></div><div>Yes, as can be seen in the Nova V2 API code this convention of adding a new extension when adding a parameter<br>has been happening for quite a while even if not explicitly documented. I think it is a reasonable expectation that a client be able to tell if a feature<br>
is supported or not rather than just guessing based on what data is returned.<br></div><div> <br>We pretty desperately need micro versioning so we're handling this<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">

directly, and not via inference from extension lists.<br>
<span class="HOEnZb"><font color="#888888"><br></font></span></blockquote><div><br><br></div><div>Microversioning is something we should consider, but with the V3 API at least the explicit versioning for on extensions is sufficient. Explicit extension versioning<br>
for say V2.1 is also a possibility.<br></div><div> <br></div><div>Chris<br></div><br></div></div></div>