<div dir="ltr"><div class="gmail_extra"><br><div class="gmail_quote">On Fri, Dec 13, 2013 at 8:12 AM, Jonathan LaCour <span dir="ltr"><<a href="mailto:jonathan-lists@cleverdevil.org" target="_blank">jonathan-lists@cleverdevil.org</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><br>
On December 11, 2013 at 2:34:07 PM, Doug Hellmann (<a href="mailto:doug.hellmann@dreamhost.com">doug.hellmann@dreamhost.com</a>) wrote:<br>
<div class="im"><br>
> On Wed, Dec 11, 2013 at 3:41 PM, Ryan Petrello wrote:<br>
> <br>
> > 1. It looks like the Nova v3 API is composed *entirely* of<br>
> > extensions (including “core” API calls), and that extensions and<br>
> > their routes are discoverable and extensible via installed<br>
> > software that registers itself via stevedore. This seems to lead<br>
> > to an API that’s composed of installed software, which in my<br>
> > opinion, makes it fairly hard to map out the API (as opposed to<br>
> > how routes are manually defined in other WSGI frameworks). I<br>
> > assume at this time, this design decision has already been<br>
> > solidified for v3?<br>
> <br>
> Yeah, I brought this up at the summit. I am still having some<br>
> trouble understanding how we are going to express a stable core API<br>
> for compatibility testing if the behavior of the API can be varied<br>
> so significantly by deployment decisions. Will we just list each<br>
> "required" extension, and forbid any extras for a compliant cloud?<br>
> <br>
> Maybe the issue is caused by me misunderstanding the term<br>
> "extension," which (to me) implies an optional component but is<br>
> perhaps reflecting a technical implementation detail instead?<br>
<br>
</div>After taking a close look at how the API is constructed, I<br>
actually think that the current approach of having the API be<br>
defined purely through extensions is flawed, for a few reasons:<br>
<br>
1. The code is extremely difficult to read and follow, because the API<br>
structure is entirely built at runtime based upon what is<br>
installed, rather than expressed declaratively in code.<br>
<br></blockquote><div><br></div><div>So I'm too close to the code to have an unbiased opinion, but I found that<br></div><div>learning the V2 API code where parts of the API (core) were defined one way <br></div><div>
and then extensions defined another even more confusing. Since they are attempting<br>to achieve the same thing.<br></div><div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
2. As a company providing a public cloud based upon OpenStack, with a<br>
desire to express compatibility with the "OpenStack API," its<br>
difficult to document the "standard" baseline Nova API. I shouldn't<br>
have to say "it depends" in API documentation.<br>
<br></blockquote><div><br></div><div>The standard baseline for the Nova V3 API will be fixed. I think its a decision higher up to<br>be made as to what is considered "OpenStack" but I'd be surprised if OpenStack<br>
compliant clouds were not permitted to add extra functionality to remain compliant.<br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
3. Based upon my read, extensions are in no way "quarantined" from the<br>
the baseline/standard/required API. In fact, they seem to be able<br>
to pollute the standard API with additional parameters and<br>
functionality. I can not envision a world in which this is sane.<br>
<br>
In my opinion, a well-designed and architected API should have the<br>
core functionality declaratively defined in the code itself, so as to<br>
give a good, well-documented, standard, and unchanging baseline. Then,<br>
an "extension" capability should be layered on in such a way that it<br>
doesn't alter the core API or serialized data.<br></blockquote><div><br></div><div>Extensions can definitely add additional parameters and functionality and<br></div><div>that has been a pretty fundamental requirement for Nova development. Perhaps this<br>
will change as Nova matures, but at the moment we'd either have to stop new<br>features being added like being able to specify to a preserve_ephemeral flag in rebuild<br>(just as one example happening in Icehouse), or have a major API version every release. <br>
</div><div><br></div><div>Note that extensions are restricted to making only backwards compatible changes<br></div><div>- eg behaviour has to stay the same if extra input parameters are not present in a<br>request, and they can only add extra output parameters, they can't change the value of<br>
existing ones.<br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
Note: my opinion isn’t altered by the fact that some of the “core” <br>
API involves “required” extensions. The result is still difficult to<br>
read and document.<br>
<br>
That said, I don’t want to diminish or minimize the hard work that<br>
has been done on the V3 API thus far! Lots of thinking and heavy<br>
lifting has already been done, and its much appreciated. I am just<br>
concerned that we lost our way somewhere. Major API revisions only<br>
come along so often, and I’d prefer to raise my objections now <br>
rather than to hold them in and regret it!<br>
<span class="HOEnZb"><font color="#888888"><br></font></span></blockquote><div><br></div><div>So the idea of the V3 API originally came out of primarily wanting to clean up many of the<br>warts, inconsistencies and bits of brokenness in the V2 API that we couldn't because<br>
of a requirement to keep backwards compatibility. Perhaps in the future Nova maturity<br>will reach the point where can start making guarantees like the core API is<br>never in anyway affected by extensions but I don't think we're there yet. <br>
<br></div><div>Chris<br></div><div class="h5"> <br></div></div></div></div>