dd4ffe3721
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
78 lines
3.5 KiB
ReStructuredText
78 lines
3.5 KiB
ReStructuredText
..
|
|
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
|
not use this file except in compliance with the License. You may obtain
|
|
a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
|
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
|
License for the specific language governing permissions and limitations
|
|
under the License.
|
|
|
|
|
|
Convention for heading levels in Neutron devref:
|
|
======= Heading 0 (reserved for the title in a document)
|
|
------- Heading 1
|
|
~~~~~~~ Heading 2
|
|
+++++++ Heading 3
|
|
''''''' Heading 4
|
|
(Avoid deeper levels because they do not render well.)
|
|
|
|
|
|
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.
|