Merge "The spec about adding parameters field for instances API"

doc/source/specs/instances-parameters.rst

@@ -0,0 +1,176 @@
+..
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://creativecommons.org/licenses/by/3.0/legalcode
+
+===================================================
+Add parameters field for protectable instances API
+===================================================
+
+https://blueprints.launchpad.net/cinder/+spec/custom-checkpoint-metadata
+
+Problem description
+===================
+
+Now the resource instances only can be queried from defaut region. If there are
+several regions in one site/keystone, we can not query resource instances
+from different region endpoint. We may need a parameter for the region name.
+
+The scene of database protection: If we want to use Protectable Instances API to
+query database instances from vendor's backup software. We must pass some parameters
+about authentication to the RESTfull API of vendor's backup software.
+
+I think we should add a dict type parameter to Protectable Instances API. The key
+and value in parameter, which is needed for implementing some Protectable plugins.
+
+
+Use Cases
+=========
+
+Scenario #1
+User need a parameter for the region name to query resource instances from different
+region endpoint.
+
+Scenario #2
+User uses the Protectable Instances API to query database instances from the vendor's
+backup software. User must provide some parameters about authentication to the RESTfull
+API of the vendor's backup software.
+
+A dict type parameter is needed for Protectable Instances API. And it is optional.
+
+Proposed change
+===============
+
+Add a new field parameters to the params of request for Protectable Instances API.
+
+  /{project_id}/protectables/{protectable_type}/instances:
+    get:
+      summary: Resource Instances
+      description: |
+        Return all the available instances for the given protectable type.
+      parameters:
+        - $ref: '#/parameters/projectParam'
+        - $ref: '#/parameters/protectable_typeParam'
+        - $ref: '#/parameters/nameFilterParam'
+        - $ref: '#/parameters/sortParam'
+        - $ref: '#/parameters/limitParam'
+        - $ref: '#/parameters/markerParam'
+        - $ref: '#/parameters/ParametersParam'
+
+The params of request: A dictionary-like object containing both the parameters from
+the query string and request body.
+
+Convert the data of parameters to the query string of API.
+
+For example:
+
+"parameters": {
+    "region_name": "USA"
+}
+
+Add the query string about the parameters to Protectable Instances API.
+
+
+/{project_id}/protectables/{protectable_type}/instances?parameters=%7B%27region_name%27%3A+%27USA%27%7D
+
+
+
+
+Alternatives
+------------
+
+Do nothing, this is not a mission critical feature.
+
+Data model impact
+-----------------
+
+None
+
+REST API impact
+---------------
+
+Add a new field parameters to the params of request for Protectable Instances API.::
+
+  /{project_id}/protectables/{protectable_type}/instances:
+    get:
+      summary: Resource Instances
+      description: |
+        Return all the available instances for the given protectable type.
+      parameters:
+        - $ref: '#/parameters/projectParam'
+        - $ref: '#/parameters/protectable_typeParam'
+        - $ref: '#/parameters/nameFilterParam'
+        - $ref: '#/parameters/sortParam'
+        - $ref: '#/parameters/limitParam'
+        - $ref: '#/parameters/markerParam'
+        - $ref: '#/parameters/ParametersParam'
+
+Security impact
+---------------
+
+None
+
+Notifications impact
+--------------------
+
+None
+
+Other end user impact
+---------------------
+
+The new API will be exposed to users via the python-karborclient.
+
+Performance Impact
+------------------
+
+None
+
+Other deployer impact
+---------------------
+
+None
+
+Developer impact
+----------------
+
+None
+
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+
+
+Work Items
+----------
+
+* Write API
+* Add to Karbor client
+* Write tests
+* Add a usage example for API
+
+Dependencies
+============
+
+None
+
+
+Testing
+=======
+
+Unit tests in Karbor and the python-karborclient.
+
+
+Documentation Impact
+====================
+
+Add a usage example for API.
+
+
+References
+==========
+
+None