summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorZuul <zuul@review.openstack.org>2018-12-28 14:35:26 +0000
committerGerrit Code Review <review@openstack.org>2018-12-28 14:35:26 +0000
commitcf41d1867c35ccb116da94a559fd30efc00b1548 (patch)
tree7758edd11ffa92850d076e595e02395d84ea82e9
parentf7b3448e0d8aaa13f994af023f7e23206ab382c7 (diff)
parentdd7a15c0ff0f48cc6ba8e7f7464f270e0d5fc5a9 (diff)
Merge "[doc] Fix api sections in the contributor doc"
-rw-r--r--doc/source/contributor/addmethod.openstackapi.rst59
-rw-r--r--doc/source/contributor/api.rst76
-rw-r--r--doc/source/contributor/index.rst3
3 files changed, 39 insertions, 99 deletions
diff --git a/doc/source/contributor/addmethod.openstackapi.rst b/doc/source/contributor/addmethod.openstackapi.rst
index fa47f56..4d09651 100644
--- a/doc/source/contributor/addmethod.openstackapi.rst
+++ b/doc/source/contributor/addmethod.openstackapi.rst
@@ -14,43 +14,60 @@
14 License for the specific language governing permissions and limitations 14 License for the specific language governing permissions and limitations
15 under the License. 15 under the License.
16 16
17Adding a Method to the OpenStack API 17Adding a Method to the OpenStack Manila API
18==================================== 18===========================================
19 19
20The 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. 20The interface to manila is a RESTful API. REST stands for Representational
21State Transfer and provides an architecture "style" for distributed systems
22using HTTP for transport. Figure out a way to express your request and
23response in terms of resources that are being created, modified, read, or
24destroyed. Manila's API aims to conform to the `guidelines <http://specs
25.openstack.org/openstack/api-sig/>`_ set by OpenStack API SIG.
21 26
22Routing 27Routing
23------- 28-------
24 29
25To map URLs to controllers+actions, OpenStack uses the Routes package, a clone of Rails routes for Python implementations. See http://routes.groovie.org/ for more information. 30To map URLs to controllers+actions, manila uses the Routes package. See
31the `routes package documentation <https://routes.readthedocs.io/en/latest/>`_
32for more information.
26 33
27URLs are mapped to "action" methods on "controller" classes in ``manila/api/v1/router.py``. 34URLs are mapped to "action" methods on "controller" classes in
35``manila/api/<VERSION>/router.py``.
28 36
29See http://routes.groovie.org/manual.html for all syntax, but you'll probably just need these two: 37These are two methods of the routes package that are used to perform the
30 - mapper.connect() lets you map a single URL to a single action on a controller. 38mapping and the routing:
31 - mapper.resource() connects many standard URLs to actions on a controller. 39
40- mapper.connect() lets you map a single URL to a single action on a
41 controller.
42- mapper.resource() connects many standard URLs to actions on a controller.
32 43
33Controllers and actions 44Controllers and actions
34----------------------- 45-----------------------
35 46
36Controllers live in ``manila/api/v1`` and ``manila/api/contrib``. 47Controllers live in ``manila/api/v1`` and ``manila/api/v2``.
37 48
38See ``manila/api/v1/shares.py`` for an example. 49See ``manila/api/v1/shares.py`` for an example.
39 50
40Action 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. 51Action methods take parameters that are sucked out of the URL by
41 52mapper.connect() or .resource(). The first two parameters are self and the
42Serialization 53WebOb request, from which you can get the req.environ, req.body,
43------------- 54req.headers, etc.
44
45Actions return a dictionary, and wsgi.Controller serializes that to JSON or XML based on the request's content-type.
46 55
47If you define a new controller, you'll need to define a ``_serialization_metadata`` attribute on the class, to tell wsgi.Controller how to convert your dictionary to XML. It needs to know the singular form of any list tag (e.g. ``<shares>`` list contains ``<share>`` tags) and which dictionary keys are to be XML attributes as opposed to subtags (e.g. ``<share id="4"/>`` instead of ``<share><id>4</id></share>``). 56Actions return a dictionary, and wsgi.Controller serializes that to JSON.
48
49See `manila/api/v1/shares.py` for an example.
50 57
51Faults 58Faults
52------ 59------
53 60
54If you need to return a non-200, you should 61If you need to return a non-200, you should return faults.Fault(webob.exc
55return faults.Fault(webob.exc.HTTPNotFound()) 62.HTTPNotFound()) replacing the exception as appropriate.
56replacing the exception as appropriate. 63
64Evolving the API
65----------------
66
67The ``v1`` version of the manila API has been deprecated. The ``v2`` version
68of the API supports micro versions. So all changes to the v2 API strive to
69maintain stability at any given API micro version, so consumers can safely
70rely on a specific micro version of the API never to change the request and
71response semantics. Read more about :doc:`API Microversions
72<api_microversion_dev>` to understand how stability and backwards
73compatibility are maintained.
diff --git a/doc/source/contributor/api.rst b/doc/source/contributor/api.rst
deleted file mode 100644
index d51b645..0000000
--- a/doc/source/contributor/api.rst
+++ /dev/null
@@ -1,76 +0,0 @@
1..
2 Copyright 2010-2011 United States Government as represented by the
3 Administrator of the National Aeronautics and Space Administration.
4 All Rights Reserved.
5
6 Licensed under the Apache License, Version 2.0 (the "License"); you may
7 not use this file except in compliance with the License. You may obtain
8 a copy of the License at
9
10 http://www.apache.org/licenses/LICENSE-2.0
11
12 Unless required by applicable law or agreed to in writing, software
13 distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
14 WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
15 License for the specific language governing permissions and limitations
16 under the License.
17
18API Endpoint
19============
20
21Manila has a system for managing multiple APIs on different subdomains.
22Currently there is support for the OpenStack API.
23
24Common Components
25-----------------
26
27The :mod:`manila.api` Module
28~~~~~~~~~~~~~~~~~~~~~~~~~~~~
29.. automodule:: manila.api
30 :noindex:
31 :members:
32 :undoc-members:
33 :show-inheritance:
34
35
36The :mod:`manila.api.v1` Module
37~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
38.. automodule:: manila.api
39 :noindex:
40 :members:
41 :undoc-members:
42 :show-inheritance:
43
44
45The :mod:`manila.api.contrib` Module
46~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
47.. automodule:: manila.api
48 :noindex:
49 :members:
50 :undoc-members:
51 :show-inheritance:
52
53
54OpenStack API
55-------------
56
57The :mod:`openstack` Module
58~~~~~~~~~~~~~~~~~~~~~~~~~~~
59.. automodule:: manila.api.openstack
60 :noindex:
61 :members:
62 :undoc-members:
63 :show-inheritance:
64
65
66Tests
67-----
68
69The :mod:`api` Module
70~~~~~~~~~~~~~~~~~~~~~
71
72.. automodule:: manila.tests.api
73 :noindex:
74 :members:
75 :undoc-members:
76 :show-inheritance:
diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst
index 8abfc85..0b6c73a 100644
--- a/doc/source/contributor/index.rst
+++ b/doc/source/contributor/index.rst
@@ -64,7 +64,7 @@ API Reference
64.. toctree:: 64.. toctree::
65 :maxdepth: 3 65 :maxdepth: 3
66 66
67 api 67 Manila API v2 Reference <https://developer.openstack.org/api-ref/shared-file-system/>
68 api_microversion_dev 68 api_microversion_dev
69 api_microversion_history 69 api_microversion_history
70 experimental_apis 70 experimental_apis
@@ -80,7 +80,6 @@ Module Reference
80 share 80 share
81 share_hooks 81 share_hooks
82 auth 82 auth
83 api
84 scheduler 83 scheduler
85 fakes 84 fakes
86 manila 85 manila