[placement] Add api-ref for resource classes

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

Change-Id: I4038d116d53b68344282ef59f9f01753766d2ef8

placement-api-ref/source/create-resource_classes-request.json

@@ -0,0 +1 @@
+{"name": "CUSTOM_FPGA"}

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

@@ -0,0 +1,9 @@
+{
+    "links": [
+        {
+            "href": "/placement/resource_classes/CUSTOM_FPGA",
+            "rel": "self"
+        }
+    ],
+    "name": "CUSTOM_FPGA"
+}

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

@@ -0,0 +1,94 @@
+{
+    "resource_classes": [
+        {
+            "links": [
+                {
+                    "href": "/placement/resource_classes/VCPU",
+                    "rel": "self"
+                }
+            ],
+            "name": "VCPU"
+        },
+        {
+            "links": [
+                {
+                    "href": "/placement/resource_classes/MEMORY_MB",
+                    "rel": "self"
+                }
+            ],
+            "name": "MEMORY_MB"
+        },
+        {
+            "links": [
+                {
+                    "href": "/placement/resource_classes/DISK_GB",
+                    "rel": "self"
+                }
+            ],
+            "name": "DISK_GB"
+        },
+        {
+            "links": [
+                {
+                    "href": "/placement/resource_classes/PCI_DEVICE",
+                    "rel": "self"
+                }
+            ],
+            "name": "PCI_DEVICE"
+        },
+        {
+            "links": [
+                {
+                    "href": "/placement/resource_classes/SRIOV_NET_VF",
+                    "rel": "self"
+                }
+            ],
+            "name": "SRIOV_NET_VF"
+        },
+        {
+            "links": [
+                {
+                    "href": "/placement/resource_classes/NUMA_SOCKET",
+                    "rel": "self"
+                }
+            ],
+            "name": "NUMA_SOCKET"
+        },
+        {
+            "links": [
+                {
+                    "href": "/placement/resource_classes/NUMA_CORE",
+                    "rel": "self"
+                }
+            ],
+            "name": "NUMA_CORE"
+        },
+        {
+            "links": [
+                {
+                    "href": "/placement/resource_classes/NUMA_THREAD",
+                    "rel": "self"
+                }
+            ],
+            "name": "NUMA_THREAD"
+        },
+        {
+            "links": [
+                {
+                    "href": "/placement/resource_classes/NUMA_MEMORY_MB",
+                    "rel": "self"
+                }
+            ],
+            "name": "NUMA_MEMORY_MB"
+        },
+        {
+            "links": [
+                {
+                    "href": "/placement/resource_classes/IPV4_ADDRESS",
+                    "rel": "self"
+                }
+            ],
+            "name": "IPV4_ADDRESS"
+        }
+    ]
+}

placement-api-ref/source/index.rst

@@ -15,5 +15,7 @@ Openstack Placement API concepts, please refer to the
 .. include:: root.inc
 .. include:: resource_providers.inc
 .. include:: resource_provider.inc
+.. include:: resource_classes.inc
+.. include:: resource_class.inc
 .. include:: inventories.inc
 .. include:: inventory.inc

placement-api-ref/source/parameters.yaml

@@ -96,6 +96,18 @@ reserved_opt:
 resource_class:
   <<: *resource_class_path
   in: body
+resource_class_links:
+  type: array
+  in: body
+  required: true
+  description: >
+    A list of links associated with one resource class.
+resource_classes:
+  type: array
+  in: body
+  required: true
+  description: >
+    A list of ``resource_class`` objects.
 resource_provider_generation:
   type: integer
   in: body

placement-api-ref/source/resource_class.inc

@@ -0,0 +1,141 @@
+==============
+Resource Class
+==============
+
+See `resource classes`_ for a description.
+This group of API calls works with a single resource class
+identified by `name`. One resource class can be listed, updated and
+deleted.
+
+.. note:: Resource class API calls are availiable starting from version 1.2.
+
+Show resource class
+===================
+
+.. rest_method:: GET /resource_classes/{name}
+
+Return a representation of the resource class identified by `{name}`.
+
+Normal Response Codes: 200
+
+Error response codes: itemNotFound(404)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - name: resource_class_path
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - name: resource_class
+  - links: resource_class_links
+
+Response Example
+----------------
+
+.. literalinclude:: get-resource_class.json
+   :language: javascript
+
+Update resource class
+=====================
+
+.. rest_method:: PUT /resource_classes/{name}
+
+Create or validate the existence of single resource class identified by `{name}`.
+
+.. note:: Method is available starting from version 1.7.
+
+Normal Response Codes: 201, 204
+
+A `201 Created` response code will be returned if the new resource class
+is successfully created.
+A `204 No Content` response code will be returned if the resource class
+already exists.
+
+Error response codes: badRequest(400)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - name: resource_class_path
+
+Response
+--------
+
+No body content is returned on a successful PUT.
+
+Update resource class (microversions 1.2 - 1.6)
+===============================================
+
+.. warning:: Changing resource class names using the <1.7 microversion is strongly discouraged.
+
+.. rest_method:: PUT /resource_classes/{name}
+
+Update the name of the resource class identified by `{name}`.
+
+Normal Response Codes: 200
+
+Error response codes: badRequest(400), itemNotFound(404), conflict(409)
+
+A `409 Conflict` response code will be returned if another resource
+class exists with the provided name.
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - name: resource_class
+
+Request example
+---------------
+
+.. literalinclude:: update-resource_class-request.json
+   :language: javascript
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - name: resource_class
+  - links: resource_class_links
+
+Response Example
+----------------
+
+.. literalinclude:: update-resource_class.json
+   :language: javascript
+
+Delete resource class
+=====================
+
+.. rest_method:: DELETE /resource_classes/{name}
+
+Delete the resource class identified by `{name}`.
+
+Normal Response Codes: 204
+
+Error response codes: itemNotFound(404), conflict(409)
+
+A `409 Conflict` response code will be returned if there exist
+inventories for the resource class.
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - name: resource_class_path
+
+Response
+--------
+
+No body content is returned on a successful DELETE.

placement-api-ref/source/resource_classes.inc

@@ -0,0 +1,65 @@
+================
+Resource Classes
+================
+
+Resource classes are entities that indicate standard or
+deployer-specific resources that can be provided by a resource
+provider.
+
+.. note:: Resource class API calls are availiable starting from version 1.2.
+
+List resource classes
+=====================
+
+.. rest_method:: GET /resource_classes
+
+Return a list of all resource classes.
+
+Normal Response Codes: 200
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - resource_classes: resource_classes
+  - links: resource_class_links
+  - name: resource_class
+
+Response Example
+----------------
+
+.. literalinclude:: get-resource_classes.json
+   :language: javascript
+
+Create resource class
+=====================
+
+.. rest_method:: POST /resource_classes
+
+Create a new resource class.
+
+Normal Response Codes: 201
+
+Error response codes: badRequest(400), conflict(409)
+
+A `409 Conflict` response code will
+be returned if another resource class exists with the provided name.
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - name: resource_class
+
+Request example
+---------------
+
+.. literalinclude:: create-resource_classes-request.json
+   :language: javascript
+
+Response
+--------
+
+No body content is returned on a successful POST.

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

@@ -0,0 +1 @@
+{"name": "CUSTOM_FPGA_V2"}

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

@@ -0,0 +1,9 @@
+{
+    "links": [
+        {
+            "href": "/placement/resource_classes/CUSTOM_FPGA_V2",
+            "rel": "self"
+        }
+    ],
+    "name": "CUSTOM_FPGA_V2"
+}