Browse Source

[doc] Fix api sections in the contributor doc

Weed out outdated/unnecessary info and add link
to api ref.

Change-Id: Ia45c8ad6e2a697d5b76232e17e4df34539d81c12
Goutham Pacha Ravi 4 months ago
parent
commit
dd7a15c0ff

+ 38
- 21
doc/source/contributor/addmethod.openstackapi.rst View File

@@ -14,43 +14,60 @@
14 14
       License for the specific language governing permissions and limitations
15 15
       under the License.
16 16
 
17
-Adding a Method to the OpenStack API
18
-====================================
17
+Adding a Method to the OpenStack Manila API
18
+===========================================
19 19
 
20
-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.
20
+The interface to manila is a RESTful API. REST stands for Representational
21
+State Transfer and provides an architecture "style" for distributed systems
22
+using HTTP for transport. Figure out a way to express your request and
23
+response in terms of resources that are being created, modified, read, or
24
+destroyed. Manila's API aims to conform to the `guidelines <http://specs
25
+.openstack.org/openstack/api-sig/>`_ set by OpenStack API SIG.
21 26
 
22 27
 Routing
23 28
 -------
24 29
 
25
-To 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.
30
+To map URLs to controllers+actions, manila uses the Routes package. See
31
+the `routes package documentation <https://routes.readthedocs.io/en/latest/>`_
32
+for more information.
26 33
 
27
-URLs are mapped to "action" methods on "controller" classes in ``manila/api/v1/router.py``.
34
+URLs are mapped to "action" methods on "controller" classes in
35
+``manila/api/<VERSION>/router.py``.
28 36
 
29
-See http://routes.groovie.org/manual.html for all syntax, but you'll probably just need these two:
30
-   - mapper.connect() lets you map a single URL to a single action on a controller.
31
-   - mapper.resource() connects many standard URLs to actions on a controller.
37
+These are two methods of the routes package that are used to perform the
38
+mapping and the routing:
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
 
33 44
 Controllers and actions
34 45
 -----------------------
35 46
 
36
-Controllers live in ``manila/api/v1`` and ``manila/api/contrib``.
47
+Controllers live in ``manila/api/v1`` and ``manila/api/v2``.
37 48
 
38 49
 See ``manila/api/v1/shares.py`` for an example.
39 50
 
40
-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.
41
-
42
-Serialization
43
--------------
44
-
45
-Actions return a dictionary, and wsgi.Controller serializes that to JSON or XML based on the request's content-type.
51
+Action methods take parameters that are sucked out of the URL by
52
+mapper.connect() or .resource().  The first two parameters are self and the
53
+WebOb request, from which you can get the req.environ, req.body,
54
+req.headers, etc.
46 55
 
47
-If 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>``).
48
-
49
-See `manila/api/v1/shares.py` for an example.
56
+Actions return a dictionary, and wsgi.Controller serializes that to JSON.
50 57
 
51 58
 Faults
52 59
 ------
53 60
 
54
-If you need to return a non-200, you should
55
-return faults.Fault(webob.exc.HTTPNotFound())
56
-replacing the exception as appropriate.
61
+If you need to return a non-200, you should return faults.Fault(webob.exc
62
+.HTTPNotFound()) replacing the exception as appropriate.
63
+
64
+Evolving the API
65
+----------------
66
+
67
+The ``v1`` version of the manila API has been deprecated. The ``v2`` version
68
+of the API supports micro versions. So all changes to the v2 API strive to
69
+maintain stability at any given API micro version, so consumers can safely
70
+rely on a specific micro version of the API never to change the request and
71
+response semantics. Read more about :doc:`API Microversions
72
+<api_microversion_dev>` to understand how stability and backwards
73
+compatibility are maintained.

+ 0
- 76
doc/source/contributor/api.rst View File

@@ -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
-
18
-API Endpoint
19
-============
20
-
21
-Manila has a system for managing multiple APIs on different subdomains.
22
-Currently there is support for the OpenStack API.
23
-
24
-Common Components
25
------------------
26
-
27
-The :mod:`manila.api` Module
28
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
29
-.. automodule:: manila.api
30
-    :noindex:
31
-    :members:
32
-    :undoc-members:
33
-    :show-inheritance:
34
-
35
-
36
-The :mod:`manila.api.v1` Module
37
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
38
-.. automodule:: manila.api
39
-    :noindex:
40
-    :members:
41
-    :undoc-members:
42
-    :show-inheritance:
43
-
44
-
45
-The :mod:`manila.api.contrib` Module
46
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
47
-.. automodule:: manila.api
48
-    :noindex:
49
-    :members:
50
-    :undoc-members:
51
-    :show-inheritance:
52
-
53
-
54
-OpenStack API
55
--------------
56
-
57
-The :mod:`openstack` Module
58
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
59
-.. automodule:: manila.api.openstack
60
-    :noindex:
61
-    :members:
62
-    :undoc-members:
63
-    :show-inheritance:
64
-
65
-
66
-Tests
67
------
68
-
69
-The :mod:`api` Module
70
-~~~~~~~~~~~~~~~~~~~~~
71
-
72
-.. automodule:: manila.tests.api
73
-    :noindex:
74
-    :members:
75
-    :undoc-members:
76
-    :show-inheritance:

+ 1
- 2
doc/source/contributor/index.rst View File

@@ -64,7 +64,7 @@ API Reference
64 64
 .. toctree::
65 65
    :maxdepth: 3
66 66
 
67
-   api
67
+   Manila API v2 Reference <https://developer.openstack.org/api-ref/shared-file-system/>
68 68
    api_microversion_dev
69 69
    api_microversion_history
70 70
    experimental_apis
@@ -80,7 +80,6 @@ Module Reference
80 80
    share
81 81
    share_hooks
82 82
    auth
83
-   api
84 83
    scheduler
85 84
    fakes
86 85
    manila

Loading…
Cancel
Save