From 090ee277c20feab6b63506251dc939a57e9920e9 Mon Sep 17 00:00:00 2001 From: Chris Dent Date: Mon, 7 Aug 2017 22:38:12 +0100 Subject: [PATCH] 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 --- guidelines/extensions.rst | 23 +++++++++++++++++------ 1 file 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 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.