Open Stack

2015-07-30 22:58 GMT+02:00 Devananda van der Veen <devananda.vdv at gmail.com>:

>
> On Thu, Jul 30, 2015 at 10:21 AM Clint Byrum <clint at fewbar.com> wrote:
>
>> Excerpts from Jim Rollenhagen's message of 2015-07-27 13:35:25 -0700:
>> > Hi friends.
>> >
>> > Ironic implemented API "micro" versions in Kilo. We originally did this
>> > to allow for breaking changes in the API while allowing users to opt in
>> > to the breakage.
>> >
>> > Since then, we've had a "default version" for our client that we bump to
>> > something sensible with each release. Currently it is at 1.8.
>> > Negotiation is done with the server to figure out what is supported and
>> > adjust accordingly.
>> >
>> > Now we've landed a patch[0] with a new version (1.11) that is not
>> > backward compatible. It causes newly added Node objects to begin life in
>> > the ENROLL state, rather than AVAILABLE. This is a good thing, and
>> > people should want this! However, it is a breaking change. Automation
>> > that adds nodes to Ironic will need to do different things after the
>> > node-create call.
>> >
>>
>> Great discussion. I think through this thread I've gained some insight
>> into what is going on, and I think the problem is that minor version
>> bumps are not for backward incompatible changes. As a user, I want to
>> pin everything and move the pins after I've tested and adapted with new
>> versions of things. However, I also don't want to have to micro manage
>> this process while I move forward on different schedules with my REST
>> clients and the Ironic service.
>>
>> So, to be clear, I may have missed what you're trying to do with micro
>> versions.
>>
>> In my world, a 1.10 -> 1.11 would be for adding new methods, new
>> arguments, or deprecating (but not removing) an existing piece of the
>> API. But changing the semantics of an existing thing is a major version
>> bump. So I wonder if the right thing to do is to bump to 2.0, make the
>> default in the client 1.10* for now, with deprecation warnings that the
>> major version will not be assumed for future client libraries, and move
>> on with the understanding that micro versions aren't supposed to break
>> users of a particular major version.
>>
>> Thoughts?
>>
>> * I'm assuming it is possible to make micro version changes to the 1.x API
>>   as 1.10.1, 1.10.2,etc
>>
>>
> Despite most folks calling this "microversions", I have been trying to
> simply call this "API version negotiation".
>
> To your question, no -- the implementations by Nova and Ironic, and the
> proposal that the API-WG has drafted [1], do not actually support
> MAJOR.MINOR.PATCH semantics.
>
> It has been implemented as a combination of an HTTP request to
> "http(s)://<server URL>/<major>/<resource URI>" plus a header "X-OpenStack-<service>-API-Version:
> <major>.<minor>".
>

What if we break this assumption? I.e. we call version in URL a "family
version" (or epoch, using more common terminology)? Then we can have API
versioning completely independent, bump <major> when needed etc.

Nothing can be done in ENROLL case IMO, but in the future we would make
such change a 3.0 version, and could "backport" changes to 2.X "branch" for
some (hopefully short) time.

I'm also really fond of idea of allowing people to request 1.latest,
2.latest, etc in this case, where 2.latest would mean "gimme all features
which I can receive without breaking, provided that I'm compatible with 2.x
branch".


>
> The <major> version number is duplicated in both the URI and the header,
> though Ironic will error if they do not match. Also, there is no <patch> or
> <micro> version.
>
> So, were we to change the <major> version in the header, I would expect
> that we also change it in the URL, which means registering a new endpoint
> with Keystone, and, well, all of that.
>
> -D
>
> [1] https://review.openstack.org/#/c/187112/
>
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>


-- 
--
-- Dmitry Tantsur
--
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150731/bd4057d8/attachment.html>