APIChangeGuidelines
API Change Guidelines
This page is represents an ongoing effort to define guidelines to help developers, code reviewers, and QA engineers evaluate whether a given API-impacting change is acceptable given the project's policy on API stability.
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
- 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:
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.
- 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)
