summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGoutham Pacha Ravi <gouthampravi@gmail.com>2018-12-21 17:11:32 -0800
committerGoutham Pacha Ravi <gouthampravi@gmail.com>2018-12-26 11:56:53 -0800
commitdd7a15c0ff0f48cc6ba8e7f7464f270e0d5fc5a9 (patch)
treefd605f84ee5fcd89096e33beb963504cb996752c
parent1a658eb18748dedba243d1baa3d759c4ec851818 (diff)
[doc] Fix api sections in the contributor doc
Weed out outdated/unnecessary info and add link to api ref. Change-Id: Ia45c8ad6e2a697d5b76232e17e4df34539d81c12
Notes
Notes (review): Code-Review+2: Tom Barron <tpb@dyncloud.net> Code-Review+2: Rodrigo Barbieri <rodrigo.barbieri2010@gmail.com> Workflow+1: Rodrigo Barbieri <rodrigo.barbieri2010@gmail.com> Verified+2: Zuul Submitted-by: Zuul Submitted-at: Fri, 28 Dec 2018 14:35:26 +0000 Reviewed-on: https://review.openstack.org/627022 Project: openstack/manila Branch: refs/heads/master
-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