[placement] Add api-ref for aggregates

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

Change-Id: Ife94d22e87a73fc26c4dcbda9545a9f59680f44f

placement-api-ref/source/aggregates.inc

@@ -0,0 +1,108 @@
+============================
+Resource provider aggregates
+============================
+
+Each resource provider can be associated with one or more other
+resource providers in groups called aggregates. API calls in this
+section are used to list and update the aggregates that are associated
+with one resource provider.
+
+.. note:: Placement aggregates are *not* the same as Nova host
+   aggregates and should not be considered equivalent.
+
+The primary differences between Nova's host aggregates and placement
+aggregates are the following:
+
+* In Nova, a host aggregate associates a *nova-compute service* with
+  other nova-compute services. Placement aggregates are not specific
+  to a nova-compute service and are, in fact, not
+  compute-specific at all. A resource provider in the Placement API is
+  generic, and placement aggregates are simply groups of generic
+  resource providers. This is an important difference especially for
+  Ironic, which when used with Nova, has many Ironic baremetal nodes
+  attached to a single nova-compute service. In the Placement API,
+  each Ironic baremetal node is its own resource provider and can
+  therefore be associated to other Ironic baremetal nodes via a
+  placement aggregate association.
+* In Nova, a host aggregate may have *metadata* key/value pairs
+  attached to it. All nova-compute services associated with a Nova
+  host aggregate share the same metadata. Placement aggregates have no
+  such metadata because placement aggregates *only* represent the
+  grouping of resource providers. In the Placement API, resource
+  providers are individually decorated with *traits* that provide
+  qualitative information about the resource provider.
+* In Nova, a host aggregate dictates the *availability zone* within
+  which one or more nova-compute services reside. Placement aggregates
+  have no concept of an availability zone.
+
+.. note:: Aggregates API requests are availiable starting from version 1.1.
+
+List resource provider aggregates
+=================================
+
+.. rest_method:: GET /resource_providers/{uuid}/aggregates
+
+Return a list of aggregates associated with the resource provider
+identified by `{uuid}`.
+
+Normal Response Codes: 200
+
+Error response codes: itemNotFound(404)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - uuid: resource_provider_uuid_path
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - aggregates: aggregates
+
+Response Example
+----------------
+
+.. literalinclude:: get-aggregates.json
+   :language: javascript
+
+Update resource provider aggregates
+===================================
+
+Associate a list of aggregates with the resource provider identified by `{uuid}`.
+
+.. rest_method:: PUT /resource_providers/{uuid}/aggregates
+
+Normal Response Codes: 200
+
+Error response codes: badRequest(400), itemNotFound(404)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - uuid: resource_provider_uuid_path
+  - aggregates: aggregates
+
+Request example
+---------------
+
+.. literalinclude:: update-aggregates-request.json
+   :language: javascript
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - aggregates: aggregates
+
+Response Example
+----------------
+
+.. literalinclude:: update-aggregates.json
+   :language: javascript

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

@@ -0,0 +1,6 @@
+{
+    "aggregates": [
+        "42896e0d-205d-4fe3-bd1e-100924931787",
+        "5e08ea53-c4c6-448e-9334-ac4953de3cfa"
+    ]
+}

placement-api-ref/source/index.rst

@@ -19,3 +19,4 @@ Openstack Placement API concepts, please refer to the
 .. include:: resource_class.inc
 .. include:: inventories.inc
 .. include:: inventory.inc
+.. include:: aggregates.inc

placement-api-ref/source/parameters.yaml

@@ -43,6 +43,12 @@ resources_query:
         resources=VCPU:4,DISK_GB:64,MEMORY_MB:2048
 
 # variables in body
+aggregates:
+  type: array
+  in: body
+  required: true
+  description: >
+    A list of aggregate uuids.
 allocation_ratio: &allocation_ratio
   type: float
   in: body

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

@@ -0,0 +1,4 @@
+[
+    "42896e0d-205d-4fe3-bd1e-100924931787",
+    "5e08ea53-c4c6-448e-9334-ac4953de3cfa"
+]

placement-api-ref/source/update-aggregates.json

@@ -0,0 +1,6 @@
+{
+    "aggregates": [
+        "42896e0d-205d-4fe3-bd1e-100924931787",
+        "5e08ea53-c4c6-448e-9334-ac4953de3cfa"
+    ]
+}