openstack/neutron-lib
Code Issues Proposed changes
Files
ecdf8785c9e346be698852f85f1d05f4a02418a8
neutron-lib/doc/source/devref/api_extensions.rst
Boden R dd4ffe3721 boilerplate extension descriptor for api-def 
Today we have a number of extensions that must provide
boilerplate/redundant code in their extension class to return
basic API definition attributes such as name, description, alias,
etc.. For example [1].

This patch proposes we can provide most of that boilerplate code
right in a base extension descriptor class; just have extension
sub-classes provide their API definition. With this patch, code such
as [1] gets reduced to a class definition with a single class-level attribute
to specify the API definition for the extension.

For sample usage, have a look at [2] that used as a dummy patch
to test PS4/PS7 of this change with neutron master.

[1] https://review.openstack.org/#/c/421562/2/neutron/extensions/providernet.py@36
[2] https://review.openstack.org/#/c/433929/1/neutron/extensions/providernet.py

Change-Id: I25135b39a1d26c11006bc2a7b6080cdd839f0085
2017-02-28 06:19:32 -07:00

3.5 KiB
Raw Blame History

API Extensions

API extensions provide a standardized way of introducing new API functionality. While the neutron-lib project itself does not serve an API, the neutron project does and leverages the API extension framework from neutron-lib.

API extensions consist of the following high-level constructs:

  • API definitions that specify the extension's static metadata. This metadata includes basic details about the extension such as its name, description, alias, etc. as well as its extended resources/sub-resources and required/optional extensions. These definitions live in the neutron_lib.api.definitions package.
  • API reference documenting the APIs/resources added/modified by the extension. This documentation is in rst format and is used to generate the openstack API reference <https://developer.openstack.org/api-ref/networking/ v2/>. The API reference lives under the api-ref/source/v2 directory of the neutron-lib project repository.
  • An extension descriptor class that must be defined in an extension directory for neutron or other sub-project that supports extensions. This concrete class provides the extension's metadata to the API server. These extension classes reside outside of neutron-lib, but leverage the base classes from neutron_lib.api.extensions. For more details see the section below on using neutron-lib's extension classes.
  • The API extension plugin implementation itself. This is the code that implements the extension's behavior and should carry out the operations defined by the extension. This code resides under its respective project repository, not in neutron-lib. For more details see the neutron api extension dev-ref <https://github.com/openstack/neutron/blob/master/doc/ source/devref/api_extensions.rst>.

Using neutron-lib's base extension classes

The neutron_lib.api.extensions module provides a set of base extension descriptor classes consumers can use to define their extension descriptor(s). For those extensions that have an API definition in neutron_lib.api.definitions, the APIExtensionDescriptor class can be used. For example:

from neutron_lib.api.definitions import provider_net
from neutron_lib.api import extensions


class Providernet(extensions.APIExtensionDescriptor):
    api_definition = provider_net
    # nothing else needed if default behavior is acceptable

For extensions that do not yet have a definition in neutron_lib.api.definitions, they can continue to use the ExtensionDescriptor as has been done historically.