[openstack-dev] [Fuel] Changing APIs and API versioning

Maciej Kwiek mkwiek at mirantis.com
Mon Nov 23 15:59:24 UTC 2015


Recently we had some cool work done regarding decoupling repositories from
fuel-web. I think it would be really good to have Fuel UI in separate
repository. +1 to the idea.

On Mon, Nov 23, 2015 at 4:56 PM, Roman Prykhodchenko <me at romcheg.me> wrote:

> Folks.
>
> This happened again. Nailgun’s API was silently changed [1] breaking
> python-fuelclient and everything else that was relying on it.
>
> I feel like this is the point when just discussing the issue is not enough
> so I call for a vote: Let’s separate Nailgun from Fuel UI and put them into
> different repositories now.
>
> Please cast your votes (either +1 or -1) to this thread. You can also
> provide your reasoning and more thoughts.
>
>
> - romcheg
>
>
> 1. https://review.openstack.org/#/c/240234/
>
> 26 жовт. 2015 р. о 11:11 Sebastian Kalinowski <skalinowski at mirantis.com>
> написав(ла):
>
> 2015-10-23 11:36 GMT+02:00 Igor Kalnitsky <ikalnitsky at mirantis.com>:
>
>> Roman, Vitaly,
>>
>> You're both saying right things, and you guys bring a sore topic up again.
>>
>> The thing is that Nailgun's API isn't the best one.. but we're trying
>> to improve it step-by-step, from release to release. We have so many
>> things to reconsider and to fix that it'd require a huge effort to
>> make backward compatible changes and support it. So we decided ignore
>> backward compatibility for clients for awhile and consider our API as
>> unstable.
>>
>> I agree with Roman that such changes must not be made secretly, and we
>> should at least announce about them. Moreover, every core must think
>> about consequences before approving them.
>>
>> So I propose to do the following things when backward incompatible
>> change to API is required:
>>
>> * Announce this change in openstack-dev ML.
>> * Wait 1 week before approving it, so anyone can prepare.
>> * Change author has to work with QA in order make sure they are
>> prepared for this change.
>>
>> Any thoughts?
>>
>
>
> +1.
>
> Although there is one thing that you didn't mention (but probably everyone
> know about it)
> is to solve the issue with fuelclient not beign tested against changes in
> nailgun.
> We need not only run it for every change in nailgun (or for only those
> that touch files under "api"
> dir) but also cover more endpoints with fuelclient tests against real API,
> not mocks, to discover
> such issues earlier.
>
>
>>
>> Thanks,
>> Igor
>>
>> On Wed, Oct 21, 2015 at 5:24 PM, Vitaly Kramskikh
>> <vkramskikh at mirantis.com> wrote:
>> > JFYI: (re-)start of this discussion was instigated by merge of this
>> change
>> > (and here is revert).
>> >
>> > And this is actually not the first time when we make backward
>> incompatible
>> > changes in our API. AFAIR, the last time it was also about the network
>> > configuration handler. We decided not to consider our API frozen, make
>> the
>> > changes and break backward compatibility. So now is the time to
>> reconsider
>> > this.
>> >
>> > API backward compatibility is a must for good software, but we also
>> need to
>> > understand that introducing API versioning is not that easy and will
>> > increase efforts needed to make new changes in nailgun.
>> >
>> > I'd go this way:
>> >
>> > Estimate the priority of introducing API versioning - maybe we have
>> other
>> > things we should invest our resources to
>> > Estimate all the disadvantages this decision might have
>> > Fix all the issues in the current API (like this one)
>> > Implement API versioning support (yes, we don't have this mechanism
>> yet, so
>> > we can't just "bump API version" like Sergii suggested in another
>> thread)
>> > Consider the current API as frozen v1, so backward incompatible changes
>> (or
>> > maybe all the changes?) should go to v2
>> >
>> >
>> > 2015-10-21 20:25 GMT+07:00 Roman Prykhodchenko <me at romcheg.me>:
>> >>
>> >> Hi folks,
>> >>
>> >> I’d like to touch the aspect of Fuel development process that seems to
>> be
>> >> as wrong as possible. That aspect is how we change the API.
>> >>
>> >> The issue is that in Fuel anyone can change API at any point of time
>> >> without even warning the rest of the same component’s team. Relying on
>> this
>> >> kind of API is basically impossible. We constantly have problems when
>> even
>> >> components of Fuel stop working due to unexpected changes in the API.
>> >> Thinking about another software that must be integrated with Fuel is
>> hardly
>> >> possible with the current approach.
>> >>
>> >> As for a grown-up project there is a strong need for Fuel in general
>> and
>> >> for Nailgun in particular to work on a policy for making changes to
>> their
>> >> APIs. Living in OpenStack ecosystem we must at least take a look how
>> it’s
>> >> done in its components and try to do something similar. After working
>> with
>> >> Nova, Keystone, Ironic and other components I would propose to start
>> with
>> >> the following: let’s not make any changes to the API. Instead, let’s
>> create
>> >> a new version of Nailgun’s API that will appear in Fuel 8.0 and make
>> all the
>> >> changes there. That is the thing that will instantaneously make lives
>> of
>> >> other components much easier, if we make it now.
>> >>
>> >> After doing the essential part let’s think about how we are going to
>> live
>> >> with that in the future. There are several APIs in Fuel, the rest of
>> the
>> >> email is only touching Nailgun’s REST API. I can see the things
>> somehow like
>> >> the following:
>> >>
>> >>  - Introduce API documentation by embedding Swagger and Swagger UI.
>> >>    The current approach when we leave API docs for documentation team
>> is
>> >> not effective. Swagger generates the documentation and resolves this
>> issue.
>> >>  - After releasing a version of Fuel, it’s API is called stable and
>> frozen
>> >> for any changes, unless they allign API to the documentation or
>> >> documentation to the API.
>> >>  - All changes to a stable APIs must be backported to the stable
>> version
>> >> of Fuel that introduced the corresponding API.
>> >>  - In order to guarantee that a stable API is not changed, Jenkins jobs
>> >> should make automatic checks for every new patch set
>> >>
>> >> Details about all the above mentioned proposals can be discussed in
>> >> separate threads so this one will stay uncluttered. I'd like to also
>> summon
>> >> those OpenStack folks, who tried to resolve the same issue and ask them
>> >> about any common solutions in the ecosystem.
>> >>
>> >>
>> >> - romcheg
>> >>
>> >>
>> >>
>> >>
>> >>
>> >>
>> __________________________________________________________________________
>> >> OpenStack Development Mailing List (not for usage questions)
>> >> Unsubscribe:
>> OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
>> <http://OpenStack-dev-request@lists.openstack.org/?subject:unsubscribe>
>> >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>> >>
>> >
>> >
>> >
>> > --
>> > Vitaly Kramskikh,
>> > Fuel UI Tech Lead,
>> > Mirantis, Inc.
>> >
>> >
>> __________________________________________________________________________
>> > OpenStack Development Mailing List (not for usage questions)
>> > Unsubscribe:
>> OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
>> <http://OpenStack-dev-request@lists.openstack.org/?subject:unsubscribe>
>> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>> >
>>
>> __________________________________________________________________________
>> OpenStack Development Mailing List (not for usage questions)
>> Unsubscribe:
>> OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
>> <http://OpenStack-dev-request@lists.openstack.org/?subject:unsubscribe>
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>
>
> __________________________________________________________________________
> 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
>
>
>
> __________________________________________________________________________
> 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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20151123/4f548285/attachment.html>


More information about the OpenStack-dev mailing list