summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChris Dent <cdent@anticdent.org>2017-08-07 22:38:12 +0100
committerEd Leafe <ed@leafe.com>2017-09-07 16:35:55 +0000
commit090ee277c20feab6b63506251dc939a57e9920e9 (patch)
tree4e6c81e1c88a3db657c2c799ba3fc6c570e0aecd
parente9be2965b289a07746521f2985144525dd7f3908 (diff)
Explain, simply, why extensions are bad
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
Notes
Notes (review): Code-Review+1: Chris Dent <cdent@anticdent.org> Code-Review+2: Ed Leafe <ed@leafe.com> Code-Review+1: Michael McCune <msm@redhat.com> Workflow+1: Ed Leafe <ed@leafe.com> Verified+2: Jenkins Submitted-by: Jenkins Submitted-at: Thu, 21 Sep 2017 16:41:18 +0000 Reviewed-on: https://review.openstack.org/491611 Project: openstack/api-wg Branch: refs/heads/master
-rw-r--r--guidelines/extensions.rst23
1 files changed, 17 insertions, 6 deletions
diff --git a/guidelines/extensions.rst b/guidelines/extensions.rst
index 4574dc3..fac14ca 100644
--- a/guidelines/extensions.rst
+++ b/guidelines/extensions.rst
@@ -5,15 +5,26 @@ API Extensions
5 5
6This topic document serves to provide guidance on the topic of API extensions. 6This topic document serves to provide guidance on the topic of API extensions.
7 7
8See also the topic document on :ref:`discoverability`. 8See also the topic documents on :ref:`discoverability` and
9:ref:`interoperability`.
9 10
10Guidance 11Guidance
11-------- 12--------
12 13
13**TODO** Add patches that give a history of current usage of API extensions in 14API extensions are sometimes used to add custom functionality to single
14OpenStack projects. 15deployments of OpenStack. They are not recommended, because when they are
16used, they break interoperability between that cloud and other OpenStack
17deployments.
15 18
16**TODO** Add patches that list the issues with API extensions. 19If a deployment requires custom behaviors over an HTTP API it should be
20implemented in a service separate from the existing OpenStack services.
17 21
18**TODO** Add a patch that makes a proposal about whether or not to recommend 22Those projects that support different functionality based on the presence
19use of API extensions. 23of drivers should strive to contain those differences to the values (not keys)
24in representation objects. Having different URLs in a service, based on
25different drivers, breaks interoperability. Where such functionality is
26absolutely required then it is critical that the functionality be discoverable
27via a capabilities API.
28
29.. note:: At this time the standards and best practices for capabilities
30 discovery are undefined.