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

[Maciej Kwiek]

Vitaly,

That's great news. I agree that we need to run fuelclient against every
change in nailgun, but on the other hand - I think we should stick to the
protocol that Igor proposed:

* 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.

Because some people we may not be aware of can rely on our API behaving in
the way it usually behaves :).

Regards,
Maciej

On Mon, Nov 23, 2015 at 5:46 PM, Vitaly Kramskikh 
wrote:

> Roman,
>
> Sorry for breaking all the stuff again. I've got suggestion to change this
> from one of the core reviewers.
>
> Fortunately, separation of Fuel UI is already in progress (Vladimir
> Kozhukalov may want to provide extra info here), but it won't guarantee
> protection from similar issues in future. What we really need is to run
> fuelclient functional tests against every change in nailgun.
>
> 2015-11-23 22:56 GMT+07:00 Roman Prykhodchenko :
>
>> 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 
>> написав(ла):
>>
>> 2015-10-23 11:36 GMT+02:00 Igor Kalnitsky :
>>
>>> 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
>>>  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 :
>>> >>
>>> >> 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
>>> 

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

[Maciej Kwiek]

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  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 
> написав(ла):
>
> 2015-10-23 11:36 GMT+02:00 Igor Kalnitsky :
>
>> 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
>>  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 :
>> >>
>> >> 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 

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

[Roman Prykhodchenko]

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  
> написав(ла):
> 
> 2015-10-23 11:36 GMT+02:00 Igor Kalnitsky  >:
> 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
> > 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  > >:
> >>
> >> 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
> 

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

[Vitaly Kramskikh]

Roman,

Sorry for breaking all the stuff again. I've got suggestion to change this
from one of the core reviewers.

Fortunately, separation of Fuel UI is already in progress (Vladimir
Kozhukalov may want to provide extra info here), but it won't guarantee
protection from similar issues in future. What we really need is to run
fuelclient functional tests against every change in nailgun.

2015-11-23 22:56 GMT+07:00 Roman Prykhodchenko :

> 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 
> написав(ла):
>
> 2015-10-23 11:36 GMT+02:00 Igor Kalnitsky :
>
>> 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
>>  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 :
>> >>
>> >> 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, 

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

[Sebastian Kalinowski]

2015-10-23 11:36 GMT+02:00 Igor Kalnitsky :

> 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
>  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 :
> >>
> >> 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.
> >>  - 

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

[Igor Kalnitsky]

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?

Thanks,
Igor

On Wed, Oct 21, 2015 at 5:24 PM, Vitaly Kramskikh
 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 :
>>
>> 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-requ...@lists.openstack.org?subject:unsubscribe
>> 

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

[Roman Prykhodchenko]

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






signature.asc
Description: Message signed with OpenPGP using GPGMail
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

[Vitaly Kramskikh]

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 :

> 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-requ...@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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev