<div dir="ltr"><div>There have now been a few iterations on the specification for Neutron micro-versioning [1].</div><div>It seems that no-one in the community opposes introducing versioning. In particular API micro-versioning as implemented by Nova and Ironic seems a decent way to evolve the API incrementally.</div><div><br></div><div>What the developer community seems not yet convinced about is moving away from extensions. It seems everybody realises the flaws of evolving the API through extensions, but there are understandable concerns regarding impact on plugins/drivers as well as the ability to differentiate, which is something quite dear to several neutron teams. I tried to consider all those concerns and feedback received; hopefully everything has been captured in a satisfactory way in the latest revision of [1].</div><div>With this ML post I also seek feedback from the API-wg concerning the current proposal, whose salient points can be summarised as follows:<br></div><div><br></div><div>#1 extensions are not part anymore of the neutron API. </div><div><br></div><div>Evolution of the API will now be handled through versioning. Once microversions are introduced:</div><div>   - current extensions will be progressively moved into the Neutron "unified" API</div><div>   - no more extension will be accepted as part of the Neutron API</div><div><br></div><div>#2 Introduction of "features" for addressing diversity in Neutron plugins</div><div><br></div><div>It is possible that the combination of neutron plugins chosen by the operator won't be able to support the whole Neutron API. For this reason a concept of "feature" is included. What features are provided depends on the plugins loaded. The list of features is hardcoded as strictly dependent on the Neutron API version implemented by the server. The specification also mandates a minimum set of features every neutron deployment must provide (those would be the minimum set of features needed for integrating Neutron with Nova).</div><div><br></div><div>#3 Advanced services are still extensions</div><div><br></div><div>This a temporary measure, as APIs for load balancing, VPN, and Edge Firewall are still served through neutron WSGI. As in the future this API will live independently it does not make sense to version them with Neutron APIs.</div><div><br></div><div>#4 Experimenting in the API</div><div><br></div><div>One thing that has plagued Neutron in the past is the impossibility of getting people to reach any sort of agreement over the shape of certain APIs. With the proposed plan we encourage developers to submit experimental APIs. Experimental APIs are unversioned and no guarantee is made regarding deprecation or backward compatibility. Also they're optional, as a deployer can turn them off. While there are caveats, like forever-experimental APIs, this will enable developer to address user feedback during the APIs' experimental phase. The Neutron community and the API-wg can provide plenty of useful feeback, but ultimately is user feedback which determines whether an API proved successful or not. Please note that the current proposal goes in a direction different from that approved in Nova when it comes to experimental APIs [3]</div><div><br></div><div>#5 Plugin/Vendor specific APIs</div><div><br></div><div>Neutron is without doubt the project with the highest number of 3rd party (OSS and commercial) integration. After all it was mostly vendors who started this project.</div><div>Vendors [4] use the extension mechanism to expose features in their products not covered by the Neutron API or to provide some sort of value-added service.</div><div>The current proposal still allows 3rd parties to attach extensions to the neutron API, provided that:</div><div>- they're not considered part of the Neutron API, in terms of versioning, documentation, and client support</div><div>- they do not redefine resources defined by the Neutron API.</div><div>- they do not live in the neutron source tree</div><div>The aim of the provisions above is to minimize the impact of such extensions on API portability.</div><div><br></div><div>Thanks for reading and thanks in advance for your feedback,<br></div><div>Salvatore</div><div><br></div><div>The title of this post has been inspired by [2]  (the message in the banner may be unintelligible to readers not fluent in european football)<br></div><div><br></div>[1] <a href="https://review.openstack.org/#/c/136760/">https://review.openstack.org/#/c/136760/</a><div>[2] <a href="http://a.espncdn.com/combiner/i/?img=/photo/2015/0502/fc-banner-jd-1296x729.jpg&w=738&site=espnfc">http://a.espncdn.com/combiner/i/?img=/photo/2015/0502/fc-banner-jd-1296x729.jpg&w=738&site=espnfc</a></div><div>[3] <a href="http://specs.openstack.org/openstack/nova-specs/specs/kilo/implemented/api-microversions.html">http://specs.openstack.org/openstack/nova-specs/specs/kilo/implemented/api-microversions.html</a></div><div>[4] By "vendor" here we refer either to a cloud provider or a company providing Neutron integration for their products.</div></div>