Merge "Create version api reference"

api-ref/source/parameters.yaml

@@ -0,0 +1,67 @@
+description:
+  description: |
+    Descriptive text about the Magnum service.
+  in: body
+  required: true
+  type: string
+links:
+  description: |
+    Links to the resources in question. See `API Guide / Links and
+    References
+    <http://docs.openstack.org/developer/nova/v2/links_and_references.html>`_
+    for more info.
+  in: body
+  required: true
+  type: array
+name:
+  description: |
+    Name of the Container Infrastructure Management API.
+  in: body
+  required: true
+  type: string
+request_id:
+  type: UUID
+  in: header
+  required: true
+  description: |
+    A unique ID for tracking service request. The request ID associated
+    with the request by default appears in the service logs.
+version:
+  description: |
+    The version.
+  in: body
+  required: true
+  type: string
+version_id:
+  type: string
+  in: body
+  required: true
+  description: >
+    A common name for the version in question. Informative only, it
+    has no real semantic meaning.
+version_max:
+  type: string
+  in: body
+  required: true
+  description: >
+    If this version of the API supports microversions, the maximum
+    microversion that is supported. This will be the empty string if
+    microversions are not supported.
+version_min:
+  type: string
+  in: body
+  required: true
+  description: >
+    If this version of the API supports microversions, the minimum
+    microversion that is supported. This will be the empty string if
+    microversions are not supported.
+version_status:
+  type: string
+  in: body
+  required: true
+  description: |
+    The status of this API version. This can be one of:
+
+    - ``CURRENT``: this is the preferred version of the API to use
+    - ``SUPPORTED``: this is an older, but still supported version of the API
+    - ``DEPRECATED``: a deprecated version of the API that is slated for removal

api-ref/source/samples/versions-01-get-resp.json

@@ -0,0 +1,60 @@
+{
+   "media_types":[
+      {
+         "base":"application/json",
+         "type":"application/vnd.openstack.magnum.v1+json"
+      }
+   ],
+   "links":[
+      {
+         "href":"http://10.164.180.104:9511/v1/",
+         "rel":"self"
+      },
+      {
+         "href":"http://docs.openstack.org/developer/magnum/dev/api-spec-v1.html",
+         "type":"text/html",
+         "rel":"describedby"
+      }
+   ],
+   "mservices":[
+      {
+         "href":"http://10.164.180.104:9511/v1/mservices/",
+         "rel":"self"
+      },
+      {
+         "href":"http://10.164.180.104:9511/mservices/",
+         "rel":"bookmark"
+      }
+   ],
+   "bays":[
+      {
+         "href":"http://10.164.180.104:9511/v1/bays/",
+         "rel":"self"
+      },
+      {
+         "href":"http://10.164.180.104:9511/bays/",
+         "rel":"bookmark"
+      }
+   ],
+   "certificates":[
+      {
+         "href":"http://10.164.180.104:9511/v1/certificates/",
+         "rel":"self"
+      },
+      {
+         "href":"http://10.164.180.104:9511/certificates/",
+         "rel":"bookmark"
+      }
+   ],
+   "baymodels":[
+      {
+         "href":"http://10.164.180.104:9511/v1/baymodels/",
+         "rel":"self"
+      },
+      {
+         "href":"http://10.164.180.104:9511/baymodels/",
+         "rel":"bookmark"
+      }
+   ],
+   "id":"v1"
+}

api-ref/source/samples/versions-get-resp.json

@@ -0,0 +1,18 @@
+{
+   "versions":[
+      {
+         "status":"CURRENT",
+         "min_version":"1.1",
+         "max_version":"1.3",
+         "id":"v1",
+         "links":[
+            {
+               "href":"http://10.164.180.104:9511/v1/",
+               "rel":"self"
+            }
+         ]
+      }
+   ],
+   "name":"OpenStack Magnum API",
+   "description":"Magnum is an OpenStack project which aims to provide container management."
+}

api-ref/source/versions.inc

@@ -0,0 +1,104 @@
+.. -*- rst -*-
+
+==============
+ API Versions
+==============
+
+In order to bring new features to users over time, the Magnum API
+supports versioning. There are two kinds of versions in Magnum.
+
+- ''major versions'', which have dedicated urls
+- ''microversions'', which can be requested through the use of the
+  ``OpenStack-API-Version``.
+
+Begining with the Newton release, all API requests support the
+``OpenStack-API-Version`` header. This header SHOULD be supplied
+with every request; in the absence of this header, each request is treated
+as though coming from an older pre-Newton client. This was done to preserve
+backwards compatibility as we introduced new features.
+
+The Version APIs work differently from other APIs as they *do not*
+require authentication.
+
+List API Versions
+=======================
+
+.. rest_method:: GET /
+
+This fetches all the information about all known major API versions in
+the deployment. Links to more specific information will be provided
+for each API version, as well as information about supported min and
+max microversions.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 503
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - X-Openstack-Request-Id: request_id
+  - versions: version
+  - status: version_status
+  - min_version: version_min
+  - max_version: version_max
+  - id: version_id
+  - links: links
+  - name: name
+  - description: description
+
+Response Example
+----------------
+
+.. literalinclude:: samples/versions-get-resp.json
+   :language: javascript
+
+
+Show v1 API Version
+====================================
+
+.. rest_method:: GET /v1/
+
+Show all the resources within the Magnum v1 API.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 503
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - X-Openstack-Request-Id: request_id
+  - id: version_id
+  - links: links
+
+.. note::
+
+   The ``media-types`` parameters in the response are
+   vestigial and provide no useful information. They will probably be
+   deprecated and removed in the future.
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/versions-01-get-resp.json
+   :language: javascript