[placement] Add api-ref for allocation_candidates

Change-Id: Id89d7c16ca53938e2bc18e904e8d13477ceb15f7

placement-api-ref/source/allocation_candidates.inc

@@ -0,0 +1,52 @@
+=====================
+Allocation candidates
+=====================
+
+.. note:: Allocation candidates API requests are availiable starting from version 1.10.
+
+List allocation candidates
+==========================
+
+Returns a dictionary representing a collection of allocation requests
+and resource provider summaries. Each allocation request has
+information to form a ``PUT /allocations/{consumer_uuid}`` request to claim
+resources against a related set of resource providers. Additional parameters
+might be required, see `Update allocations`_. As several allocation
+requests are available it's necessary to select one. To make a
+decision, resource provider summaries are provided with the
+inventory/capacity information. For example, this information is used by
+nova-scheduler's FilterScheduler to make decisions about on which compute host
+to build a server.
+
+.. rest_method:: GET /allocation_candidates
+
+Normal Response Codes: 200
+
+Error response codes: badRequest(400)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - resources: resources_query_required
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - allocation_requests: allocation_requests
+  - provider_summaries: provider_summaries
+  - allocations: allocations_array
+  - resource_provider: resource_provider_object
+  - uuid: resource_provider_uuid
+  - resources: resources
+  - capacity: capacity
+  - used: used
+
+Response Example
+----------------
+
+.. literalinclude:: get-allocation_candidates.json
+   :language: javascript

placement-api-ref/source/get-allocation_candidates.json

@@ -0,0 +1,34 @@
+{
+    "allocation_requests": [
+        {
+            "allocations": [
+                {
+                    "resource_provider": {
+                        "uuid": "30742363-f65e-4012-a60a-43e0bec38f0e"
+                    },
+                    "resources": {
+                        "MEMORY_MB": 512
+                    }
+                }
+            ]
+        }
+    ],
+    "provider_summaries": {
+        "30742363-f65e-4012-a60a-43e0bec38f0e": {
+            "resources": {
+                "DISK_GB": {
+                    "capacity": 77,
+                    "used": 0
+                },
+                "MEMORY_MB": {
+                    "capacity": 11206,
+                    "used": 256
+                },
+                "VCPU": {
+                    "capacity": 64,
+                    "used": 0
+                }
+            }
+        }
+    }
+}

placement-api-ref/source/index.rst

@@ -24,3 +24,4 @@ Openstack Placement API concepts, please refer to the
 .. include:: resource_provider_allocations.inc
 .. include:: usages.inc
 .. include:: resource_provider_usages.inc
+.. include:: allocation_candidates.inc

placement-api-ref/source/parameters.yaml

@@ -49,7 +49,7 @@ resource_provider_uuid_query:
   <<: *resource_provider_uuid_path
   in: query
   required: false
-resources_query:
+resources_query: &resources_query
   type: string
   in: query
   required: false
@@ -59,6 +59,9 @@ resources_query:
     capacity to serve::
 
         resources=VCPU:4,DISK_GB:64,MEMORY_MB:2048
+resources_query_required:
+  <<: *resources_query
+  required: true
 trait_associated:
   type: string
   in: query
@@ -110,6 +113,15 @@ allocation_ratio: &allocation_ratio
 allocation_ratio_opt:
   <<: *allocation_ratio
   required: false
+allocation_requests:
+  type: array
+  in: body
+  required: true
+  description: >
+    A list of objects that contain a
+    serialized HTTP body that a client may subsequently use in a call
+    to PUT /allocations/{consumer_uuid} to claim resources against a
+    related set of resource providers.
 allocations_array:
   type: array
   in: body
@@ -122,6 +134,12 @@ allocations_by_resource_provider:
   required: true
   description: >
     A dictionary of allocations keyed by resource provider uuid.
+capacity:
+  type: integer
+  in: body
+  required: true
+  description: >
+    The amount of the resource that the provider can accommodate.
 inventories:
   type: object
   in: body
@@ -150,6 +168,13 @@ project_id_body:
   <<: *project_id
   in: body
   min_version: 1.8
+provider_summaries:
+  type: object
+  in: body
+  required: true
+  description: >
+    A dictionary keyed by resource provider UUID,
+    of dictionaries of inventory/capacity information.
 reserved: &reserved
   type: integer
   in: body
@@ -207,7 +232,7 @@ resource_provider_object:
   in: body
   required: true
   description: >
-    A dictionary contains uuid of the resource provider.
+    A dictionary which contains the UUID of the resource provider.
 resource_provider_usages:
   type: object
   in: body
@@ -258,6 +283,12 @@ traits:
   required: true
   description: >
     A list of traits.
+used:
+  type: integer
+  in: body
+  required: true
+  description: >
+    The amount of the resource that has been already allocated.
 user_id_body:
   <<: *user_id
   in: body