openstack/nova
Code Issues Proposed changes

doc: Remove useless contributor/api-2 doc

Browse Source 
There's nothing of use in here. A section on creating extensions for the
API is removed since this is no longer a thing.

Change-Id: I18a6f642c046051cd6084ab920d78f27887ca13d
Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
This commit is contained in:
Stephen Finucane 2022-02-09 18:09:18 +00:00
parent 9a31212a44
commit 7beff288d6
5 changed files with 60 additions and 117 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
doc/source/_extra/.htaccess
View File

@ -1,4 +1,4 @@
redirectmatch 301 ^/nova/([^/]+)/addmethod.openstackapi.html$ /nova/$1/contributor/api-2.html
redirectmatch 301 ^/nova/([^/]+)/addmethod.openstackapi.html$ /nova/$1/contributor/api.html
redirectmatch 301 ^/nova/([^/]+)/admin/flavors2.html$ /nova/$1/admin/flavors.html
redirectmatch 301 ^/nova/([^/]+)/admin/numa.html$ /nova/$1/admin/cpu-topologies.html
redirectmatch 301 ^/nova/([^/]+)/admin/quotas2.html$ /nova/$1/admin/quotas.html
@ -85,3 +85,4 @@ redirectmatch 301 ^/nova/([^/]+)/admin/system-admin.html$ /nova/$1/admin/index.h
redirectmatch 301 ^/nova/([^/]+)/admin/port_with_resource_request.html$ /nova/$1/admin/ports-with-resource-requests.html
redirectmatch 301 ^/nova/([^/]+)/admin/manage-users.html$ /nova/$1/admin/architecture.html
redirectmatch 301 ^/nova/([^/]+)/admin/mitigation-for-Intel-MDS-security-flaws.html /nova/$1/admin/cpu-models.html
redirectmatch 301 ^/nova/([^/]+)/contributor/api-2.html$ /nova/$1/contributor/api.html

56
doc/source/contributor/api-2.rst
View File

@ -1,56 +0,0 @@
..
Copyright 2010-2011 OpenStack Foundation
All Rights Reserved.
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.
.. TODO::
This should be merged into contributor/api
Adding a Method to the OpenStack API
====================================
The interface is a mostly RESTful API. REST stands for Representational State Transfer and provides an architecture "style" for distributed systems using HTTP for transport. Figure out a way to express your request and response in terms of resources that are being created, modified, read, or destroyed.
Routing
-------
To map URLs to controllers+actions, OpenStack uses the Routes package, a clone of Rails routes for Python implementations. See http://routes.readthedocs.io/en/latest/ for more information.
URLs are mapped to "action" methods on "controller" classes in ``nova/api/openstack/__init__/ApiRouter.__init__`` .
See http://routes.readthedocs.io/en/latest/modules/mapper.html for all syntax, but you'll probably just need these two:
- mapper.connect() lets you map a single URL to a single action on a controller.
- mapper.resource() connects many standard URLs to actions on a controller.
Controllers and actions
-----------------------
Controllers live in ``nova/api/openstack``, and inherit from nova.wsgi.Controller.
See ``nova/api/openstack/compute/servers.py`` for an example.
Action methods take parameters that are sucked out of the URL by mapper.connect() or .resource(). The first two parameters are self and the WebOb request, from which you can get the req.environ, req.body, req.headers, etc.
Serialization
-------------
Actions return a dictionary, and wsgi.Controller serializes that to JSON.
Faults
------
If you need to return a non-200, you should
return faults.Fault(webob.exc.HTTPNotFound())
replacing the exception as appropriate.

112
doc/source/contributor/api.rst
View File

@ -1,23 +1,38 @@
Extending the API
=================
Background
----------
.. note::
This document provides general background information on how one can extend
the REST API in nova. For information on the microversion support including
how to add new microversions, see :doc:`/contributor/microversions`. For
information on how to use the API, refer to the `API guide`__ and `API
reference guide`__.
.. __: https://docs.openstack.org/api-guide/compute/
.. __: https://docs.openstack.org/api-ref/compute/
Nova's API is a mostly RESTful API. REST stands for *Representational State
Transfer* and provides an architecture "style" for distributed systems using
HTTP for transport. Figure out a way to express your request and response in
terms of resources that are being created, modified, read, or destroyed.
Nova has v2.1 API frameworks which supports microversions.
This document covers how to add API for the v2.1 API framework. A
:doc:`microversions specific document <microversions>` covers the details
:doc:`microversions-specific document <microversions>` covers the details
around what is required for the microversions part.
The v2.1 API framework is under ``nova/api`` and each API is implemented in
``nova/api/openstack/compute``.
Note that any change to the Nova API to be merged will first require a
spec be approved first. See `here <https://opendev.org/openstack/nova-specs>`_
for the appropriate repository. For guidance on the design of the API
please refer to the `OpenStack API WG
<https://wiki.openstack.org/wiki/API_Working_Group>`_
.. note::
Any change to the Nova API to be merged will first require a spec be
approved first.
See `here <https://opendev.org/openstack/nova-specs>`_ for the appropriate
repository.
For guidance on the design of the API please refer to the `OpenStack API WG
<https://wiki.openstack.org/wiki/API_Working_Group>`_
Basic API Controller
@ -25,7 +40,9 @@ Basic API Controller
API controller includes the implementation of API methods for a resource.
A very basic controller of a v2.1 API::
A very basic controller of a v2.1 API:
.. code-block:: python
"""Basic Controller"""
@ -51,6 +68,8 @@ A very basic controller of a v2.1 API::
# Defining support for other RESTFul methods based on resource.
# ...
See `servers.py <https://opendev.org/openstack/nova/src/branch/master/nova/api/openstack/compute/servers.py>`_ for ref.
@ -63,7 +82,9 @@ The URL mapping is based on the plain list which routes the API request to
appropriate controller and method. Each API needs to add its route information
in ``nova/api/openstack/compute/routes.py``.
A basic skeleton of URL mapping in routers.py::
A basic skeleton of URL mapping in ``routers.py``:
.. code-block:: python
"""URL Mapping Router List"""
@ -74,7 +95,8 @@ A basic skeleton of URL mapping in routers.py::
# Create a controller object
basic_controller = functools.partial(
_create_controller, basic_api.BasicController, [], [])
_create_controller, basic_api.BasicController, [], [],
)
# Routing list structure:
# (
@ -88,20 +110,16 @@ A basic skeleton of URL mapping in routers.py::
# ...
# )
ROUTE_LIST = (
.
.
.
# ...
('/basic', {
'GET': [basic_controller, 'index'],
'POST': [basic_controller, 'create']
}),
.
.
.
# ...
)
Complete routing list can be found in `routes.py <https://opendev.org/openstack/nova/src/branch/master/nova/api/openstack/compute/routes.py>`_.
Complete routing list can be found in `routes.py
<https://opendev.org/openstack/nova/src/branch/master/nova/api/openstack/compute/routes.py>`_.
Policy
~~~~~~
@ -113,7 +131,7 @@ Modularity
~~~~~~~~~~
The Nova REST API is separated into different controllers in the directory
'nova/api/openstack/compute/'
``nova/api/openstack/compute/``.
Because microversions are supported in the Nova REST API, the API can be
extended without any new controller. But for code readability, the Nova REST API
@ -140,39 +158,13 @@ JSON-Schema
The v2.1 API validates a REST request body with JSON-Schema library.
Valid body formats are defined with JSON-Schema in the directory
'nova/api/openstack/compute/schemas'. Each definition is used at the
corresponding method with the ``validation.schema`` decorator like::
``nova/api/openstack/compute/schemas``. Each definition is used at the
corresponding method with the ``validation.schema`` decorator like:
.. code-block:: python
@validation.schema(schema.update_something)
def update(self, req, id, body):
....
Similarly to controller modularity, JSON-Schema definitions can be added
in same or separate JSON-Schema module.
The following are the combinations of extensible API and method name
which returns additional JSON-Schema parameters:
* Create a server API - get_server_create_schema()
For example, keypairs extension(Keypairs class) contains the method
get_server_create_schema() which returns::
{
'key_name': parameter_types.name,
}
then the parameter key_name is allowed on Create a server API.
.. note:: Currently only create schema are implemented in modular way.
Final goal is to merge them all and define the concluded
process in this doc.
These are essentially hooks into the servers controller which allow other
controller to modify behaviour without having to modify servers.py. In
the past not having this capability led to very large chunks of
unrelated code being added to servers.py which was difficult to
maintain.
def update(self, req, id, body):
Unit Tests
@ -187,7 +179,7 @@ Negative tests would include such things as:
* Request schema validation failures, for both the request body and query
parameters
* HTTPNotFound or other >=400 response code failures
* ``HTTPNotFound`` or other >=400 response code failures
Functional tests and API Samples
@ -203,6 +195,7 @@ The API samples tests are made of two parts:
``doc/api_samples/``. There is typically one directory per API controller
with subdirectories per microversion for that API controller. The unversioned
samples are used for the base v2.0 / v2.1 APIs.
* Corresponding API sample templates found under path
``nova/tests/functional/api_sample_tests/api_samples``. These have a similar
structure to the API reference docs samples, except the format of the sample
@ -220,7 +213,7 @@ need to be made.
Note that it is possible to automatically generate the API reference doc
samples using the templates by simply running the tests using
``tox -r -e api-samples``. This relies, of course, upon the test and templates
``tox -e api-samples``. This relies, of course, upon the test and templates
being correct for the test to pass, which may take some iteration.
In general, if you are adding a new microversion to an existing API controller,
@ -228,7 +221,7 @@ it is easiest to simply copy an existing test and modify it for the new
microversion and the new samples/templates.
The functional API samples tests are not the simplest thing in the world to
get used to, and can be very frustrating at times when they fail in not
get used to and it can be very frustrating at times when they fail in not
obvious ways. If you need help debugging a functional API sample test failure,
feel free to post your work-in-progress change for review and ask for help in
the ``openstack-nova`` OFTC IRC channel.
@ -270,11 +263,13 @@ The general steps for deprecating a REST API are:
* Set a maximum allowed microversion for the route. Requests beyond that
microversion on that route will result in a ``404 HTTPNotFound`` error.
* Update the Compute API reference documentation to indicate the route is
deprecated and move it to the bottom of the list with the other deprecated
APIs.
* Deprecate, and eventually remove, related CLI / SDK functionality in other
projects like python-novaclient.
projects like *python-novaclient*.
Removing deprecated APIs
@ -294,15 +289,20 @@ The general steps for removing support for a deprecated REST API are:
microversion that does not support a deprecated API. 410 means the resource
is gone and not coming back, which is more appropriate when the API is
fully removed and will not work at any microversion.
* Related configuration options, policy rules, and schema validation are
removed.
* The API reference documentation should be updated to move the documentation
for the removed API to the `Obsolete APIs`_ section and mention in which
release the API was removed.
* Unit tests can be removed.
* API sample functional tests can be changed to assert the 410 response
behavior, but can otherwise be mostly gutted. Related \*.tpl files for the
API sample functional tests can be deleted since they will not be used.
* An "upgrade" :doc:`release note <releasenotes>` should be added to mention
the REST API routes that were removed along with any related configuration
options that were also removed.

3
doc/source/contributor/index.rst
View File

@ -140,8 +140,6 @@ changes done to the API, as the impact can be very wide.
* :doc:`/contributor/api`: How the code is structured inside the API layer
* :doc:`/contributor/api-2`: (needs update)
* :doc:`/contributor/microversions`: How the API is (micro)versioned and what
you need to do when adding an API exposed feature that needs a new
microversion.
@ -160,7 +158,6 @@ extend.
:hidden:
api
api-2
microversions
api-ref-guideline
notifications

3
doc/test/redirect-tests.txt
View File

@ -1,4 +1,4 @@
/nova/latest/addmethod.openstackapi.html 301 /nova/latest/contributor/api-2.html
/nova/latest/addmethod.openstackapi.html 301 /nova/latest/contributor/api.html
/nova/latest/admin/arch.html 301 /nova/latest/admin/architecture.html
/nova/latest/admin/flavors2.html 301 /nova/latest/admin/flavors.html
/nova/latest/admin/quotas2.html 301 /nova/latest/admin/quotas.html
@ -86,3 +86,4 @@
/nova/latest/admin/port_with_resource_request.html 301 /nova/latest/admin/ports-with-resource-requests.html
/nova/latest/admin/manage-users.html 301 /nova/latest/admin/architecture.html
/nova/latest/admin/mitigation-for-Intel-MDS-security-flaws.html 301 /nova/latest/admin/cpu-models.html
/nova/latest/contributor/api-2.html 301 /nova/latest/contributor/api.html