Create certificates api reference

Add details for certificates API of Magnum.

Change-Id: Iabf72dc4387d086d2d9b25963a0413ccf2372514
Implements: blueprint magnum-doc-rest-api

api-ref/source/certificates.inc

@@ -0,0 +1,100 @@
+.. -*- rst -*-
+
+=====================================
+ Manage certificates for bay/cluster
+=====================================
+
+Generates and show CA certificates for bay/cluster.
+
+Show details about the CA certificate for a bay/cluster
+=======================================================
+
+.. rest_method:: GET /v1/certificates/{bay_uuid/cluster_uuid}
+
+Show CA certificate details that are associated with the created bay/cluster.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 401
+   - 403
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - bay_uuid: bay_cluster_id
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - X-Openstack-Request-Id: request_id
+  - pem: pem
+  - bay_uuid: bay_cluster_id
+  - links: links
+
+Response Example
+----------------
+
+.. literalinclude:: samples/certificates-ca-show-resp.json
+   :language: javascript
+
+Generate the CA certificate for a bay/cluster
+=============================================
+
+.. rest_method:: POST /v1/certificates/
+
+Sign client key and generate the CA certificate for a bay/cluster
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 201
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - bay_uuid: bay_cluster_id
+  - csr: csr
+
+Request Example
+----------------
+
+.. literalinclude:: samples/certificates-ca-sign-req.json
+   :language: javascript
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - X-Openstack-Request-Id: request_id
+  - pem: pem
+  - bay_uuid: bay_cluster_id
+  - links: links
+  - csr: csr
+
+Response Example
+----------------
+
+.. literalinclude:: samples/certificates-ca-sign-resp.json
+   :language: javascript

api-ref/source/parameters.yaml

@@ -5,6 +5,12 @@ request_id:
   description: |
     A unique ID for tracking service request. The request ID associated
     with the request by default appears in the service logs.
+bay_cluster_id:
+  type: UUID
+  in: body
+  required: true
+  description: |
+    The UUID of the bay/cluster.
 binary:
   type: string
   in: body
@@ -29,6 +35,15 @@ created_at:
   in: body
   required: true
   type: string
+csr:
+  description: |
+    Certificate Signing Request (CSR) for authenticating client key.
+
+    The CSR will be used by Magnum to generate a signed certificate
+    that client will use to communicate with the Bay/Cluster.
+  in: body
+  required: true
+  type: string
 description:
   description: |
     Descriptive text about the Magnum service.
@@ -56,10 +71,7 @@ id_s:
   type: string
 links:
   description: |
-    Links to the resources in question. See `API Guide / Links and
+    Links to the resources in question.
-    References
-    <http://docs.openstack.org/developer/nova/v2/links_and_references.html>`_
-    for more info.
   in: body
   required: true
   type: array
@@ -75,6 +87,12 @@ name:
   in: body
   required: true
   type: string
+pem:
+  description: |
+    CA certificate for the bay/cluster.
+  in: body
+  required: true
+  type: string
 report_count:
   description: |
     The total number of report.

api-ref/source/samples/certificates-ca-show-resp.json

@@ -0,0 +1,14 @@
+{
+   "pem":"-----BEGIN CERTIFICATE-----\nMIICzDCCAbSgAwIBAgIQOOkVcEN7TNa9E80GoUs4xDANBgkqhkiG9w0BAQsFADAO\n-----END CERTIFICATE-----\n",
+   "bay_uuid":"0b4b766f-1500-44b3-9804-5a6e12fe6df4",
+   "links":[
+      {
+         "href":"http://10.164.180.104:9511/v1/certificates/0b4b766f-1500-44b3-9804-5a6e12fe6df4",
+         "rel":"self"
+      },
+      {
+         "href":"http://10.164.180.104:9511/certificates/0b4b766f-1500-44b3-9804-5a6e12fe6df4",
+         "rel":"bookmark"
+      }
+   ]
+}

api-ref/source/samples/certificates-ca-sign-req.json

@@ -0,0 +1,4 @@
+{
+   "bay_uuid":"0b4b766f-1500-44b3-9804-5a6e12fe6df4",
+   "csr":"-----BEGIN CERTIFICATE REQUEST-----\nMIIEfzCCAmcCAQAwFDESMBAGA1UEAxMJWW91ciBOYW1lMIICIjANBgkqhkiG9w0B\n-----END CERTIFICATE REQUEST-----\n"
+}

api-ref/source/samples/certificates-ca-sign-resp.json

@@ -0,0 +1,15 @@
+{
+   "pem":"-----BEGIN CERTIFICATE-----\nMIIDxDCCAqygAwIBAgIRALgUbIjdKUy8lqErJmCxVfkwDQYJKoZIhvcNAQELBQAw\n-----END CERTIFICATE-----\n",
+   "bay_uuid":"0b4b766f-1500-44b3-9804-5a6e12fe6df4",
+   "links":[
+      {
+         "href":"http://10.164.180.104:9511/v1/certificates/0b4b766f-1500-44b3-9804-5a6e12fe6df4",
+         "rel":"self"
+      },
+      {
+         "href":"http://10.164.180.104:9511/certificates/0b4b766f-1500-44b3-9804-5a6e12fe6df4",
+         "rel":"bookmark"
+      }
+   ],
+   "csr":"-----BEGIN CERTIFICATE REQUEST-----\nMIIEfzCCAmcCAQAwFDESMBAGA1UEAxMJWW91ciBOYW1lMIICIjANBgkqhkiG9w0B\n-----END CERTIFICATE REQUEST-----\n"
+}