[placement] Add api-ref for allocations

This provides simple documentation of the path, request and response
body parameters when listing, creating, updating and deleting allocations.

Change-Id: I58e9dfcb62a2f485addeab98dcd835568ba792cf

placement-api-ref/source/allocations.inc

@@ -0,0 +1,106 @@
+===========
+Allocations
+===========
+
+Allocations are records representing resources that have been assigned
+and used by some consumer of that resource. They indicate the amount
+of a particular resource that has been allocated to a given consumer
+of that resource from a particular resource provider.
+
+List allocations
+================
+
+List all allocation records for the consumer identified by
+`{consumer_uuid}` on all the resource providers it is consuming.
+
+.. rest_method:: GET /allocations/{consumer_uuid}
+
+Normal Response Codes: 200
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - consumer_uuid: consumer_uuid
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - allocations: allocations_by_resource_provider
+  - generation: resource_provider_generation
+  - resources: resources
+
+Response Example
+----------------
+
+.. literalinclude:: get-allocations.json
+   :language: javascript
+
+Update allocations
+==================
+
+Create or update one or more allocation records representing the consumption of
+one or more classes of resources from one or more resource providers by
+the consumer identified by `{consumer_uuid}`.
+If allocations already exist for this consumer, they are replaced.
+
+.. rest_method:: PUT /allocations/{consumer_uuid}
+
+Normal Response Codes: 204
+
+Error response codes: badRequest(400), itemNotFound(404), conflict(409)
+
+* `409 Conflict` if there is no available inventory in any of the
+  resource providers for any specified resource classes or inventories
+  are updated by another thread while attempting the operation.
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - consumer_uuid: consumer_uuid
+  - allocations: allocations_array
+  - resources: resources
+  - resource_provider: resource_provider_object
+  - uuid: resource_provider_uuid
+  - project_id: project_id_body
+  - user_id: user_id_body
+
+Request example
+---------------
+
+.. literalinclude:: update-allocations-request.json
+   :language: javascript
+
+Response
+--------
+
+No body content is returned on a successful PUT.
+
+Delete allocations
+==================
+
+Delete all allocation records for the consumer identified by
+`{consumer_uuid}` on all resource providers it is consuming.
+
+.. rest_method:: DELETE /allocations/{consumer_uuid}
+
+Normal Response Codes: 204
+
+Error response codes: itemNotFound(404)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - consumer_uuid: consumer_uuid
+
+Response
+--------
+
+No body content is returned on a successful DELETE.

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

@@ -0,0 +1,17 @@
+{
+    "allocations": {
+        "92637880-2d79-43c6-afab-d860886c6391": {
+            "generation": 2,
+            "resources": {
+                "DISK_GB": 5
+            }
+        },
+        "ba8e1ef8-7fa3-41a4-9bb4-d7cb2019899b": {
+            "generation": 8,
+            "resources": {
+                "MEMORY_MB": 512,
+                "VCPU": 2
+            }
+        }
+    }
+}

placement-api-ref/source/index.rst

@@ -22,3 +22,4 @@ Openstack Placement API concepts, please refer to the
 .. include:: aggregates.inc
 .. include:: traits.inc
 .. include:: resource_provider_traits.inc
+.. include:: allocations.inc

placement-api-ref/source/parameters.yaml

@@ -1,4 +1,10 @@
 # variables in path
+consumer_uuid:
+  type: string
+  in: path
+  required: true
+  description: >
+    The uuid of a consumer.
 resource_class_path: &resource_class_path
   type: string
   in: path
@@ -27,6 +33,12 @@ member_of:
     A comma-separated list of strings representing aggregate uuids.
     The returned resource providers must be associated with at
     least one of the aggregates identified by uuid.
+project_id: &project_id
+  type: string
+  in: query
+  required: true
+  description: >
+    The uuid of a project.
 resource_provider_name_query:
   type: string
   in: query
@@ -67,6 +79,12 @@ trait_name_query:
 
     `in` operator filters the traits whose name is in the specified list, e.g.
     name=in:HW_CPU_X86_AVX,HW_CPU_X86_SSE,HW_CPU_X86_INVALID_FEATURE.
+user_id: &user_id
+  type: string
+  in: query
+  required: false
+  description: >
+    The uuid of a user.
 
 # variables in body
 aggregates:
@@ -92,6 +110,18 @@ allocation_ratio: &allocation_ratio
 allocation_ratio_opt:
   <<: *allocation_ratio
   required: false
+allocations_array:
+  type: array
+  in: body
+  required: true
+  description: >
+    A list of dictionaries.
+allocations_by_resource_provider:
+  type: object
+  in: body
+  required: true
+  description: >
+    A dictionary of allocations keyed by resource provider uuid.
 inventories:
   type: object
   in: body
@@ -116,6 +146,10 @@ min_unit: &min_unit
 min_unit_opt:
   <<: *min_unit
   required: false
+project_id_body:
+  <<: *project_id
+  in: body
+  min_version: 1.8
 reserved: &reserved
   type: integer
   in: body
@@ -162,6 +196,12 @@ resource_provider_name:
   required: true
   description: >
     The name of one resource provider.
+resource_provider_object:
+  type: object
+  in: body
+  required: true
+  description: >
+    A dictionary contains uuid of the resource provider.
 resource_provider_uuid:
   <<: *resource_provider_uuid_path
   in: body
@@ -175,6 +215,12 @@ resource_providers:
   required: true
   description: >
     A list of ``resource_provider`` objects.
+resources:
+  type: object
+  in: body
+  required: true
+  description: >
+    A dictionary of resource records keyed by resource class name.
 step_size: &step_size
   type: integer
   in: body
@@ -198,6 +244,11 @@ traits:
   required: true
   description: >
     A list of traits.
+user_id_body:
+  <<: *user_id
+  in: body
+  required: true
+  min_version: 1.8
 version_id:
   type: string
   in: body

placement-api-ref/source/update-allocations-request.json

@@ -0,0 +1,23 @@
+{
+    "allocations": [
+        {
+            "resource_provider": {
+                "uuid": "844ac34d-620e-474c-833c-4c9921251353"
+            },
+            "resources": {
+                "MEMORY_MB": 512,
+                "VCPU": 2
+            }
+        },
+        {
+            "resource_provider": {
+                "uuid": "92637880-2d79-43c6-afab-d860886c6391"
+            },
+            "resources": {
+                "DISK_GB": 5
+            }
+        }
+    ],
+    "project_id": "6e3b2ce9-9175-4830-a862-b9de690bdceb",
+    "user_id": "81c516e3-5e0e-4dcb-9a38-4473d229a950"
+}