From 8ab4b7a1eda985aa5e9fe9d70dad0389c86f3b12 Mon Sep 17 00:00:00 2001
From: Chris Dent <cdent@anticdent.org>
Date: Tue, 10 Jan 2017 17:33:13 +0000
Subject: [PATCH] [placement] add api-ref for GET /resource_providers

This provides simple documentation of the response body and query
parameters when listing resource providers.

Change-Id: Ic8db81b5f17d4c380b64b3da24e525297db18584
---
 .../source/get-resource_providers.json        | 50 +++++++++++++++
 placement-api-ref/source/index.rst            | 49 +++++++++++++++
 placement-api-ref/source/parameters.yaml      | 62 +++++++++++++++++++
 3 files changed, 161 insertions(+)
 create mode 100644 placement-api-ref/source/get-resource_providers.json

diff --git a/placement-api-ref/source/get-resource_providers.json b/placement-api-ref/source/get-resource_providers.json
new file mode 100644
index 000000000000..be1a72a3a28f
--- /dev/null
+++ b/placement-api-ref/source/get-resource_providers.json
@@ -0,0 +1,50 @@
+{
+  "resource_providers": [
+    {
+      "generation": 1,
+      "uuid": "99c09379-6e52-4ef8-9a95-b9ce6f68452e",
+      "links": [
+        {
+          "href": "/resource_providers/99c09379-6e52-4ef8-9a95-b9ce6f68452e",
+          "rel": "self"
+        },
+        {
+          "href": "/resource_providers/99c09379-6e52-4ef8-9a95-b9ce6f68452e/aggregates",
+          "rel": "aggregates"
+        },
+        {
+          "href": "/resource_providers/99c09379-6e52-4ef8-9a95-b9ce6f68452e/inventories",
+          "rel": "inventories"
+        },
+        {
+          "href": "/resource_providers/99c09379-6e52-4ef8-9a95-b9ce6f68452e/usages",
+          "rel": "usages"
+        }
+      ],
+      "name": "vgr.localdomain"
+    },
+    {
+      "generation": 2,
+      "uuid": "d0b381e9-8761-42de-8e6c-bba99a96d5f5",
+      "links": [
+        {
+          "href": "/resource_providers/d0b381e9-8761-42de-8e6c-bba99a96d5f5",
+          "rel": "self"
+        },
+        {
+          "href": "/resource_providers/d0b381e9-8761-42de-8e6c-bba99a96d5f5/aggregates",
+          "rel": "aggregates"
+        },
+        {
+          "href": "/resource_providers/d0b381e9-8761-42de-8e6c-bba99a96d5f5/inventories",
+          "rel": "inventories"
+        },
+        {
+          "href": "/resource_providers/d0b381e9-8761-42de-8e6c-bba99a96d5f5/usages",
+          "rel": "usages"
+        }
+      ],
+      "name": "pony1"
+    }
+  ]
+}
diff --git a/placement-api-ref/source/index.rst b/placement-api-ref/source/index.rst
index 5044dcda7f93..6e0dd3ac01d7 100644
--- a/placement-api-ref/source/index.rst
+++ b/placement-api-ref/source/index.rst
@@ -44,3 +44,52 @@ Response Example
 
 .. literalinclude:: get-root.json
    :language: javascript
+
+==================
+Resource Providers
+==================
+
+Resource providers are entities which provide consumable inventory of one or
+more classes of resource (such as disk or memory). They can be listed (with
+filters), created, updated and deleted.
+
+List Resource Providers
+=======================
+
+.. rest_method:: GET /resource_providers
+
+List an optionally filtered collection of resource providers.
+
+Normal Response Codes: 200
+
+Request
+-------
+
+Several query parameters are available to filter the returned list of
+resource providers. If multiple different parameters are provided, the results
+of all filters are merged with a boolean `AND`.
+
+.. rest_parameters:: parameters.yaml
+
+  - resources: resources_query
+  - member_of: member_of
+  - uuid: resource_provider_uuid_query
+  - name: resource_provider_name_query
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - resource_providers: resource_providers
+  - generation: resource_provider_generation
+  - uuid: resource_provider_uuid
+  - links: resource_provider_links
+  - name: resource_provider_name
+
+
+Response Example
+----------------
+
+.. literalinclude:: get-resource_providers.json
+   :language: javascript
diff --git a/placement-api-ref/source/parameters.yaml b/placement-api-ref/source/parameters.yaml
index 9a8f9e96492e..69c35e85dd97 100644
--- a/placement-api-ref/source/parameters.yaml
+++ b/placement-api-ref/source/parameters.yaml
@@ -1,3 +1,65 @@
+member_of:
+  type: string
+  in: query
+  required: false
+  description: >
+    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.
+resource_provider_name_query:
+  type: string
+  in: query
+  required: false
+  description: >
+    The name of a resource provider to filter the list.
+resource_provider_uuid_query:
+  type: string
+  in: query
+  required: false
+  description: >
+    The uuid of a resource provider to filter the list.
+resources_query:
+  type: string
+  in: query
+  required: false
+  description: |
+    A comma-separated list of strings indicating an amount of
+    resource of a specified class that a provider must have the
+    capacity to serve::
+
+        resources=VCPU:4,DISK_GB:64,MEMORY_MB:2048
+
+resource_provider_generation:
+  type: integer
+  in: body
+  required: true
+  description: >
+    A consistent view marker that assists with the management of
+    concurrent resource provider updates.
+resource_provider_links:
+  type: array
+  in: body
+  required: true
+  description: >
+    A list of links associated with one resource provider.
+resource_provider_name:
+  type: string
+  in: body
+  required: true
+  description: >
+    The name of one resource provider.
+resource_provider_uuid:
+  type: string
+  in: body
+  required: true
+  description: >
+    The UUID for one resource provider.
+resource_providers:
+  type: array
+  in: body
+  required: true
+  description: >
+    A list of ``resource_provider`` objects.
 version_id:
   type: string
   in: body