Open Stack

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




-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 842 bytes
Desc: Message signed with OpenPGP using GPGMail
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20151021/dc3685d0/attachment.pgp>