Governance/Proposed/Policy for Changes to OpenStack APIs

Time: <<DateTime(2012-07-26T20:44:59Z)>>

Drafters Email: <<MailTo(david DOT kranz AT qrclab DOT com)>>

Status: To be completed by POC

Policy for Incompatible Changes to OpenStack APIs

An approach one can take, adopted in Java, is marking an API as "deprecated", and supporting them till the next big release. It alerts developers of new code to avoid using it, alerts current users to use an alternative API (which we document with an example, conversion strategy along with the deprecated marker).

I like the 2XX approach for success, in hardware machine specific registers we document that certain bits are reserved for future use and not to rely on their current value. This is an approach also used in error messages in software, 1000 for A type problem, 2000 for B type problem. But in particular the 200 OK is a legacy from HTML days, perhaps a difficult one to shake off!

It is critical to the success of OpenStack that operators be willing to upgrade to new OpenStack releases. All OpenStack APIs use a versioning scheme that is completely independent from the named releases (Essex, Folsom, etc.). One obstacle to upgrading to a new OpenStack release is if there are incompatible API changes that could cause user applications to stop working. Operators want great new features and APIs to be the only aspect of the upgrade process visible to their users. Old API versions should continue to work.

On the other hand, OpenStack is a maturing project and operators want to see bugs fixed. Each of these bug fixes may introduce subtle behavioral changes that could potentially cause issues for existing clients which rely on the buggy behavior.

Each cloud operator may have their own idea of where the line should be drawn between legitimate bug fixes and and incompatible API changes. Some operators may be in the early stages of their deployment and value the bug fixes while not having a significant user base they are concerned about. Other operators may be highly risk averse and would prefer to see bug compatibility retained for ever rather than have a change impact a single user.

OpenStack should take a clear view of where this line is drawn and we - developers, code reviewers, and QA engineers - should endeavour to apply a consistent set of guidelines when considering a change which may affect clients of an existing API version.

As always, guidelines are just guidelines. We can never hope to prescribe an exact set of rules for each possible scenario.

Generally Considered OK

The change is the only way to fix a security bug
Fixing a bug so that a request which resulted in an error response before is now successful
Adding a property to a resource representation <--- Rackspace has forced through API changes to remove added properties and have suggested they would act to prevent adding a property to a resource representation because of The Spec (which happens to map identically to the existing CloudServers API)
Adding an optional property to a resource representation which may be supplied by clients, assuming the API previously would ignore this property
Adding a new response header
Changing an error response code to be more accurate

Generally Not Acceptable

A change such that a request which was successful before now results in an error response (unless the success reported previously was hiding an existing error condition)
Changing or removing a property in a resource representation
Changing the semantics of a property in a resource representation which may be supplied by clients
Changing or removing a response header
Changing which response code is returned on success

No, Really. We Mean It!

You may feel a particular case is special and warrants an incompatible API change. Consider some responses to commonly used justifications.

The change is needed to improve API consistency.

Your desire to improve API consistency is appreciated, but all APIs have warts. Inconsistencies that need breaking changes can be fixed in a new API version. Please find a way to channel your efforts into preparations to fix these consistencies in the next API version.ome harder even in a new API version.

It is unlikely that any existing users of the API would be affected.

It is difficult to predict how people are using the APIs. Developers do the strangest things. As our APIs become more adopted over time, it will only become more futile to attempt to make such predictions. One thing you can do is to help improve our documentation about how our APIs should be used. If we can document in future versions that we do not make guarantees about certain behaviours, that may give us some small additional leeway when it comes to making changes.

The existing API is not well documented

If an API's behavior isn't adequately documented, then developers using the API have no choice but to go by what they observe the behavior to be.

The change does not impact users of OpenStack's client libraries or command line interfaces

We encourage developers to develop against OpenStack REST API. There will be many tools and applications which favor the REST API over our libraries or command line interfaces.

Examples

Failing Silently

At one point the change password nova API would return success even if the system was unable to do it:

https://bugs.launchpad.net/nova/+bug/1022961

This made sense to fix because this any client checking the response code of this request surely wants to know if the request failed. Any existing client which this change affects was broken anyway because it was failing to actually change the admin password.

Questions/Notes/Observations

Should (4) in the "OK" section be allowed? It would not break programs but has the problem that there is no way for the user of an API to know which arguments are supported.

It would be really nice to be able to do this better. One idea would be to have the notion of a "minor" version for an OpenStack release that is not bumping the major version along with a new API to query for a minor version level from an API endpoint. That way new, non breaking, features could be added and clients could know if they were supported or not. That could even include totally new APIs.

In future APIs, we should specify which variant of 2xx is returned on success
What about multiple installations of OpenStack? Many of the change types we list as OK (adding attributes, adding headers) would have not detrimental effect when working against a single OpenStack installation that was upgrading, but would proove problematic if someone wrote their code to a newer version of the v2 API, but then tried to use it against a different OpenStack installation which was slightly older.

Hence the suggestion about a minor version so that such an app could check.