placement: Return new provider from POST /rps

To facilitate opaqueness of resource provider generation internals, we
need to return the (initial) generation when a provider is created. For
consistency with other APIs, we will do this by returning the entire
resource provider record (which includes the generation) from POST
/resource_providers.

Change-Id: I8624e194fe0173531c5aa2119c903e3c68b8c6cd
blueprint: generation-from-create-provider

placement-api-ref/source/parameters.yaml

@@ -313,7 +313,7 @@ resource_provider_generation_optional:
 resource_provider_generation_v1_19:
   <<: *resource_provider_generation
   min_version: 1.19
-resource_provider_links:
+resource_provider_links: &resource_provider_links
   type: array
   in: body
   required: true
@@ -326,6 +326,11 @@ resource_provider_links:
       Traits relationship link is available starting from version 1.6.
       Allocations relationship link is available starting from version 1.11.
 
+resource_provider_links_v1_20:
+  <<: *resource_provider_links
+  description: |
+    A list of links associated with the resource provider.
+
 resource_provider_name:
   type: string
   in: body
@@ -344,14 +349,20 @@ resource_provider_parent_provider_uuid: &resource_provider_parent_provider_uuid
   required: false
   description: >
     The UUID of the immediate parent of the resource provider.
+resource_provider_parent_provider_uuid_1_14: &resource_provider_parent_provider_uuid_1_14
+  <<: *resource_provider_parent_provider_uuid
   min_version: 1.14
 resource_provider_parent_provider_uuid_required:
   <<: *resource_provider_parent_provider_uuid
   required: true
-resource_provider_root_provider_uuid_required:
+resource_provider_root_provider_uuid_no_min: &resource_provider_root_provider_uuid_no_min
   type: string
   in: body
   required: true
+  description: >
+    UUID of the top-most provider in this provider tree.
+resource_provider_root_provider_uuid_required:
+  <<: *resource_provider_root_provider_uuid_no_min
   description: >
     Read-only UUID of the top-most provider in this provider tree.
   min_version: 1.14

placement-api-ref/source/resource_provider.inc

@@ -64,7 +64,7 @@ Request
 
   - uuid: resource_provider_uuid_path
   - name: resource_provider_name
-  - parent_provider_uuid: resource_provider_parent_provider_uuid
+  - parent_provider_uuid: resource_provider_parent_provider_uuid_1_14
 
 Request example
 ---------------

placement-api-ref/source/resource_providers.inc

@@ -63,7 +63,8 @@ Create resource provider
 
 Create a new resource provider.
 
-Normal Response Codes: 201
+Normal Response Codes: 201 (microversions 1.0 - 1.19), 200 (microversions
+1.20 - )
 
 Error response codes: conflict(409)
 
@@ -78,7 +79,7 @@ Request
 
   - name: resource_provider_name
   - uuid: resource_provider_uuid_opt
-  - parent_provider_uuid: resource_provider_parent_provider_uuid
+  - parent_provider_uuid: resource_provider_parent_provider_uuid_1_14
 
 Request example
 ---------------
@@ -86,11 +87,30 @@ Request example
 .. literalinclude:: ./samples/resource_providers/create-resource_providers-request.json
    :language: javascript
 
-Response
---------
+Response (microversions 1.0 - 1.19)
+-----------------------------------
 
 .. rest_parameters:: parameters.yaml
 
   - Location: location
 
 No body content is returned on a successful POST.
+
+Response (microversions 1.20 - )
+--------------------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - Location: location
+  - generation: resource_provider_generation
+  - uuid: resource_provider_uuid
+  - links: resource_provider_links_v1_20
+  - name: resource_provider_name
+  - parent_provider_uuid: resource_provider_parent_provider_uuid
+  - root_provider_uuid: resource_provider_root_provider_uuid_no_min
+
+Response Example (microversions 1.20 - )
+----------------------------------------
+
+.. literalinclude:: ./samples/resource_providers/create-resource_provider.json
+   :language: javascript

placement-api-ref/source/samples/resource_providers/create-resource_provider.json

@@ -0,0 +1,33 @@
+{
+    "generation": 0,
+    "links": [
+        {
+            "href": "/placement/resource_providers/7d2590ae-fb85-4080-9306-058b4c915e3f",
+            "rel": "self"
+        },
+        {
+            "href": "/placement/resource_providers/7d2590ae-fb85-4080-9306-058b4c915e3f/aggregates",
+            "rel": "aggregates"
+        },
+        {
+            "href": "/placement/resource_providers/7d2590ae-fb85-4080-9306-058b4c915e3f/inventories",
+            "rel": "inventories"
+        },
+        {
+            "href": "/placement/resource_providers/7d2590ae-fb85-4080-9306-058b4c915e3f/usages",
+            "rel": "usages"
+        },
+        {
+            "href": "/placement/resource_providers/7d2590ae-fb85-4080-9306-058b4c915e3f/traits",
+            "rel": "traits"
+        },
+        {
+            "href": "/placement/resource_providers/7d2590ae-fb85-4080-9306-058b4c915e3f/allocations",
+            "rel": "allocations"
+        }
+    ],
+    "name": "NFS Share",
+    "uuid": "7d2590ae-fb85-4080-9306-058b4c915e3f",
+    "parent_provider_uuid": "542df8ed-9be2-49b9-b4db-6d3183ff8ec8",
+    "root_provider_uuid": "542df8ed-9be2-49b9-b4db-6d3183ff8ec8"
+}