- 1 API Change Guidelines
- 1.1 Guidelines
- 1.2 No, Really. We Mean It!
- 1.3 Examples
- 1.3.1 Failing Silently
- 1.3.2 Out Of Spec Features Belong in Extensions
- 1.3.3 Adding New Header OK; Changing Response Code Not So Much
- 1.3.4 Silly Extension
- 1.3.5 Bugfixes OK
- 1.3.6 Extension Aliases
- 1.3.7 500 error
- 1.3.8 Inconsistent Handling of Volume Attach Device
- 1.3.9 null values
- 1.3.10 Missing Property From XML Representation
- 1.4 Related Mailing List Discussions
- 1.5 Questions/Notes/Observations
API Change Guidelines
This page 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.
Edits to help clarify these guidelines are very welcome. However, before making any substantial changes, please discuss the proposed change on the openstack-dev mailing list.
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 new response header
- Changing an error response code to be more accurate
- OK when conditionally added as a new API extension
- 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
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.
Please help document concrete examples of how these guidelines are being applied in the various core projects.
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.
Out Of Spec Features Belong in Extensions
The config_drive attribute on servers is not part of the 1.1 Compute API spec, so it was moved into an extension which could be disabled.
Adding New Header OK; Changing Response Code Not So Much
Rather than returning "200 OK" for successful volume creation, we should return "201 Created" and include a Location header.
It was decided that it is safe to add the Location header, but not change the response code.
Sometimes you come across an extension that makes no sense and is highly unlikely to be used by anyone.
- https://bugs.launchpad.net/nova/+bug/1030106 - fix incorrect counting of hosts in instance usage audit log
- https://review.openstack.org/#/c/10812/ - Make extension aliases consistent
- https://bugs.launchpad.net/nova/+bug/1035120 - Server create with malformed body yields a 500 error
- https://bugs.launchpad.net/nova/+bug/1038227 - malformed server update causes: KeyError: 'server'
Inconsistent Handling of Volume Attach Device
- https://review.openstack.org/#/c/10908/ - Allow nova to guess device if not passed to attach
- https://bugs.launchpad.net/nova/+bug/1039266 - null values in extensions are inconsistent
Missing Property From XML Representation
- https://bugs.launchpad.net/nova/+bug/1039276 - hypervisor_hostname in extended server status doesn't appear in xml
Related Mailing List Discussions
- Standardizing status codes in the native API (July 2012)
- 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)
- 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!