openstack/api-sig
Code Issues Proposed changes
api-sig/guidelines/extensions.rst
Chris Dent 090ee277c2 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
2017-09-07 16:35:55 +00:00

1.1 KiB
Raw Permalink Blame History

API Extensions

This topic document serves to provide guidance on the topic of API extensions.

See also the topic documents on discoverability and interoperability.

Guidance

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.

If a deployment requires custom behaviors over an HTTP API it should be implemented in a service separate from the existing OpenStack services.

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.