openstack/api-sig
Code Issues Proposed changes

Explain, simply, why extensions are bad

Browse Source 
This tries to keep it as simple as possible and refrains from going into
history or examples, because it's not clear if any of that is relevant
beyond the interop concern.

Change-Id: Iae9f93ab73e17a626858641d2528f7a7c03c80b2
Closes-Bug: #1593331
Closes-Bug: #1593330
Closes-Bug: #1593328
This commit is contained in:
Chris Dent 2017-08-07 22:38:12 +01:00 committed by Ed Leafe
parent e9be2965b2
commit 090ee277c2
1 changed files with 17 additions and 6 deletions

23
guidelines/extensions.rst

@ -5,15 +5,26 @@ API Extensions
This topic document serves to provide guidance on the topic of API extensions.
See also the topic document on :ref:`discoverability`.
See also the topic documents on :ref:`discoverability` and
:ref:`interoperability`.
Guidance
--------
**TODO** Add patches that give a history of current usage of API extensions in
OpenStack projects.
API extensions are sometimes used to add custom functionality to single
deployments of OpenStack. They are not recommended, because when they are
used, they break interoperability between that cloud and other OpenStack
deployments.
**TODO** Add patches that list the issues with API extensions.
If a deployment requires custom behaviors over an HTTP API it should be
implemented in a service separate from the existing OpenStack services.
**TODO** Add a patch that makes a proposal about whether or not to recommend
use of API extensions.
Those projects that support different functionality based on the presence
of drivers should strive to contain those differences to the values (not keys)
in representation objects. Having different URLs in a service, based on
different drivers, breaks interoperability. Where such functionality is
absolutely required then it is critical that the functionality be discoverable
via a capabilities API.
.. note:: At this time the standards and best practices for capabilities
discovery are undefined.