Add detail=[True, False] query string to API list endpoints

We currently support /[nodes, ports, portgroups, chassis]/detail as an
API endpoint for getting a detailed list of each object. This does not
fit the RESTful and resourceful API design principles of <resource
type>/<resource id> and makes it hard to consume the API from frameworks
that expect that structure. We can't remove the old endpoint, so that is
safeguarded by the restricted node names list. This patch adds a
?detail=[True, False] query string to the list API endpoints to allow
those consuming the API to use the expected URL form.

Change-Id: I694919b4a4eaa3419318bbee1cde79de15e19afa
Story: #1662921
Task: #10176

4 files changed, 24 insertions, 1 deletions

diff --git a/api-ref/source/baremetal-api-v1-chassis.inc b/api-ref/source/baremetal-api-v1-chassis.inc
index 39563dcac..f52b9d5b7 100644
--- a/api-ref/source/baremetal-api-v1-chassis.inc
+++ b/api-ref/source/baremetal-api-v1-chassis.inc
@@ -203,6 +203,10 @@ List chassis
 
 Lists all chassis.
 
+.. versionadded:: 1.43
+  Added the ``detail`` boolean request parameter. When specified ``True`` this
+  causes the response to include complete details about each chassis.
+
 Normal response codes: 200
 
 .. TODO: add error codes
@@ -217,6 +221,7 @@ Request
    - sort_dir: sort_dir
    - sort_key: sort_key
    - fields: fields
+   - detail: detail
 
 Response Parameters
 -------------------
diff --git a/api-ref/source/baremetal-api-v1-nodes.inc b/api-ref/source/baremetal-api-v1-nodes.inc
index e85d5f279..6a6eaf1d1 100644
--- a/api-ref/source/baremetal-api-v1-nodes.inc
+++ b/api-ref/source/baremetal-api-v1-nodes.inc
@@ -132,7 +132,7 @@ and any defaults added for non-specified fields. Most fields default to "null"
 or "".
 
 The list and example below are representative of the response as of API
-microversion 1.42.
+microversion 1.43.
 
 .. rest_parameters:: parameters.yaml
 
@@ -215,6 +215,10 @@ provision state, and maintenance setting for each Node.
 .. versionadded:: 1.42
   Introduced the ``fault`` field.
 
+.. versionadded:: 1.43
+  Added the ``detail`` boolean request parameter. When specified ``True`` this
+  causes the response to include complete details about each node.
+
 Normal response codes: 200
 
 Error codes: 400,403,406
@@ -236,6 +240,7 @@ Request
    - marker: marker
    - sort_dir: sort_dir
    - sort_key: sort_key
+   - detail: detail
 
 Response
 --------
@@ -261,6 +266,9 @@ List Nodes Detailed
 
 .. rest_method::  GET /v1/nodes/detail
 
+.. deprecated::
+   Use ?detail=True query string instead.
+
 Return a list of bare metal Nodes with complete details. Some filtering is
 possible by passing in flags with the request.
 
diff --git a/api-ref/source/baremetal-api-v1-portgroups.inc b/api-ref/source/baremetal-api-v1-portgroups.inc
index 6149ff054..b1fc4dea2 100644
--- a/api-ref/source/baremetal-api-v1-portgroups.inc
+++ b/api-ref/source/baremetal-api-v1-portgroups.inc
@@ -28,6 +28,10 @@ some parameters with the request.
 
 By default, this query will return the UUID, name and address for each Portgroup.
 
+.. versionadded:: 1.43
+  Added the ``detail`` boolean request parameter. When specified ``True`` this
+  causes the response to include complete details about each portgroup.
+
 Normal response code: 200
 
 Error codes: 400,401,403,404
@@ -44,6 +48,7 @@ Request
     - marker: marker
     - sort_dir: sort_dir
     - sort_key: sort_key
+    - detail: detail
 
 Response
 --------
diff --git a/api-ref/source/baremetal-api-v1-ports.inc b/api-ref/source/baremetal-api-v1-ports.inc
index 88e08a53a..db58297dd 100644
--- a/api-ref/source/baremetal-api-v1-ports.inc
+++ b/api-ref/source/baremetal-api-v1-ports.inc
@@ -42,6 +42,10 @@ By default, this query will return the uuid and address for each Port.
 .. versionadded:: 1.34
   Added the ``physical_network`` field.
 
+.. versionadded:: 1.43
+  Added the ``detail`` boolean request parameter. When specified ``True`` this
+  causes the response to include complete details about each port.
+
 Normal response code: 200
 
 Request
@@ -58,6 +62,7 @@ Request
     - marker: marker
     - sort_dir: sort_dir
     - sort_key: sort_key
+    - detail: detail
 
 Response
 --------