[placement] Add api-ref for RP usages

Add placement-api-ref for resource provider usages.

Co-Authored-by: Andrey Volkov <avolkov@gmail.com>

Change-Id: I6ba8765a427f654dafb32fc3fbf5492b0e1b426a

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

@@ -0,0 +1,8 @@
+{
+    "resource_provider_generation": 1,
+    "usages": {
+        "DISK_GB": 1,
+        "MEMORY_MB": 512,
+        "VCPU": 1
+    }
+}

placement-api-ref/source/index.rst

@@ -4,8 +4,6 @@
  Placement API
 ===============
 
-.. TODO(cdent) this is a big pile of todo
-
 This is a reference for the Openstack Placement API. To learn more about
 Openstack Placement API concepts, please refer to the
 `Placement Introduction <http://docs.openstack.org/developer/nova/placement.html>`_.
@@ -25,3 +23,4 @@ Openstack Placement API concepts, please refer to the
 .. include:: allocations.inc
 .. include:: resource_provider_allocations.inc
 .. include:: usages.inc
+.. include:: resource_provider_usages.inc

placement-api-ref/source/parameters.yaml

@@ -208,6 +208,14 @@ resource_provider_object:
   required: true
   description: >
     A dictionary contains uuid of the resource provider.
+resource_provider_usages:
+  type: object
+  in: body
+  required: true
+  description: >
+    The usage summary of the resource provider. This is a dictionary that
+    describes how much each class of resource is being consumed on this
+    resource provider. For example, ``"VCPU": 1`` means 1 VCPU is used.
 resource_provider_uuid:
   <<: *resource_provider_uuid_path
   in: body

placement-api-ref/source/resource_provider_usages.inc

@@ -0,0 +1,42 @@
+========================
+Resource provider usages
+========================
+
+Show the consumption of resources for a resource provider
+in an aggregated form, i.e. without information for a particular consumer.
+See `Resource provider allocations`_.
+
+List resource provider usages
+=============================
+
+Return a report of usage information for resources associated with
+the resource provider identified by `{uuid}`. The value is a dictionary
+of resource classes paired with the sum of the allocations of that
+resource class for this resource provider.
+
+.. rest_method:: GET /resource_providers/{uuid}/usages
+
+Normal Response Codes: 200
+
+Error response codes: itemNotFound(404)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - uuid: resource_provider_uuid_path
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - resource_provider_generation: resource_provider_generation
+  - usages: resource_provider_usages
+
+Response Example
+----------------
+
+.. literalinclude:: get-resource_provider_usages.json
+   :language: javascript