From 2e51f95263b4e999b6cfe20ebc1667fab207a3cc Mon Sep 17 00:00:00 2001 From: Mark Goddard Date: Wed, 12 Jul 2017 16:41:31 +0100 Subject: [PATCH] Improve ports API reference Currently there are a few missing fields and API microversion notes in the ports API reference. This change resolves those issues. All ports microversion notes have been changed to use the active voice. Change-Id: If16c8e311e439e88fbbdd693c12e0f7992af5044 --- .../source/baremetal-api-v1-nodes-ports.inc | 14 ++++ .../baremetal-api-v1-portgroups-ports.inc | 9 ++- api-ref/source/baremetal-api-v1-ports.inc | 64 ++++++++++++------- 3 files changed, 61 insertions(+), 26 deletions(-) diff --git a/api-ref/source/baremetal-api-v1-nodes-ports.inc b/api-ref/source/baremetal-api-v1-nodes-ports.inc index a83cb7ab5a..5e4f74778e 100644 --- a/api-ref/source/baremetal-api-v1-nodes-ports.inc +++ b/api-ref/source/baremetal-api-v1-nodes-ports.inc @@ -18,6 +18,15 @@ List Ports by Node Return a list of bare metal Ports associated with ``node_ident``. +API microversion 1.8 added the ``fields`` request parameter. When specified, +this causes the content of the response to include only the specified fields, +rather than the default set. + +API microversion 1.19 added the ``pxe_enabled`` and ``local_link_connection`` +fields. + +API microversion 1.24 added the ``portgroup_uuid`` field. + API microversion 1.34 added the ``physical_network`` field. Normal response code: 200 @@ -58,6 +67,11 @@ List detailed Ports by Node Return a detailed list of bare metal Ports associated with ``node_ident``. +API microversion 1.19 added the ``pxe_enabled`` and ``local_link_connection`` +fields. + +API microversion 1.24 added the ``portgroup_uuid`` field. + API microversion 1.34 added the ``physical_network`` field. Normal response code: 200 diff --git a/api-ref/source/baremetal-api-v1-portgroups-ports.inc b/api-ref/source/baremetal-api-v1-portgroups-ports.inc index b0e7583fbc..72175cf66e 100644 --- a/api-ref/source/baremetal-api-v1-portgroups-ports.inc +++ b/api-ref/source/baremetal-api-v1-portgroups-ports.inc @@ -10,9 +10,9 @@ of, and details of, all Ports associated with that Portgroup. These endpoints do not allow modification of the Ports; that should be done by accessing the Port resources under the ``/v1/ports`` endpoint. -``/v1/portgroups/{portgroup_ident}/ports`` endpoint was added in API -microversion 1.24, if using older version, all the requests return -``Not Found (404)`` error code. +API microversion 1.24 added the ``/v1/portgroups/{portgroup_ident}/ports`` +endpoint. If using an older version, all requests to this endpoint will return +a ``Not Found (404)`` error code. List Ports by Portgroup @@ -22,6 +22,9 @@ List Ports by Portgroup Return a list of bare metal Ports associated with ``portgroup_ident``. +When specified, the ``fields`` request parameter causes the content of the +Response to include only the specified fields, rather than the default set. + API microversion 1.34 added the ``physical_network`` field. Normal response code: 200 diff --git a/api-ref/source/baremetal-api-v1-ports.inc b/api-ref/source/baremetal-api-v1-ports.inc index 074fc242ba..bc9d65203e 100644 --- a/api-ref/source/baremetal-api-v1-ports.inc +++ b/api-ref/source/baremetal-api-v1-ports.inc @@ -9,9 +9,9 @@ resources are done through the ``ports`` resource. All Ports must be associated to a Node when created. This association can be changed, though the request may be rejected if either the current -or destination Node are in a transitive state (eg, in the process of deploying) -or are in a state that would be non-deterministically affected by such a change -(e.g., there is an active user instance on the Node). +or destination Node are in a transitive state (e.g., in the process of +deploying) or are in a state that would be non-deterministically affected by +such a change (e.g., there is an active user instance on the Node). List Ports @@ -24,20 +24,18 @@ some parameters with the request. By default, this query will return the uuid and address for each Port. -``node`` query parameter was added in API microversion 1.6. If both -``node_uuid`` and ``node`` are specified in the request, ``node_uuid`` -will be used to filter results. +API microversion 1.6 added the ``node`` query parameter. If both ``node_uuid`` +and ``node`` are specified in the request, ``node_uuid`` will be used to filter +results. -API microversion 1.8 added the ``fields`` Request parameter. When specified, -this causes the content of the Response to include only the specified fields, +API microversion 1.8 added the ``fields`` request parameter. When specified, +this causes the content of the response to include only the specified fields, rather than the default set. API microversion 1.19 added the ``pxe_enabled`` and ``local_link_connection`` fields. -.. TODO: add pxe_enabled and local_link_connection to all sample files - -API microversion 1.24 added the portgroup_uuid field. +API microversion 1.24 added the ``portgroup_uuid`` field. API microversion 1.34 added the ``physical_network`` field. @@ -84,7 +82,13 @@ Creates a new Port resource. This method requires a Node UUID and the physical hardware address for the Port (MAC address in most cases). -``physical_network`` response field was added in API microversion 1.34. +API microversion 1.19 added the ``pxe_enabled`` and ``local_link_connection`` +request and response fields. + +API microversion 1.24 added the ``portgroup_uuid`` request and response fields. + +API microversion 1.34 added the ``physical_network`` request and response +fields. Normal response code: 201 @@ -95,7 +99,11 @@ Request - node_uuid: node_uuid - address: port_address + - portgroup_uuid: portgroup_uuid + - local_link_connection: local_link_connection + - pxe_enabled: pxe_enabled - physical_network: physical_network + - extra: extra **Example Port creation request:** @@ -133,14 +141,17 @@ List Detailed Ports Return a list of bare metal Ports, with detailed information. -``node`` query parameter was added in API microversion 1.6. If both -``node_uuid`` and ``node`` are specified in the request, ``node_uuid`` -will be used to filter results. +API microversion 1.6 added the ``node`` query parameter. If both ``node_uuid`` +and ``node`` are specified in the request, ``node_uuid`` will be used to filter +results. -``portgroup`` query parameter and ``portgroup_uuid`` response field -were added in API microversion 1.24. +API microversion 1.19 added the ``pxe_enabled`` and ``local_link_connection`` +response fields. -``physical_network`` response field was added in API microversion 1.34. +API microversion 1.24 added the ``portgroup`` query parameter and +``portgroup_uuid`` response field. + +API microversion 1.34 added the ``physical_network`` response field. Normal response code: 200 @@ -190,14 +201,16 @@ Show Port Details Show details for the given Port. -API microversion 1.8 added the ``fields`` Request parameter. When specified, -this causes the content of the Response to include only the specified fields, +API microversion 1.8 added the ``fields`` request parameter. When specified, +this causes the content of the response to include only the specified fields, rather than the default set. -``portgroup`` query parameter and ``portgroup_uuid`` response field -were added in API microversion 1.24. +API microversion 1.19 added the ``pxe_enabled`` and ``local_link_connection`` +response fields. -``physical_network`` response field was added in API microversion 1.34. +API microversion 1.24 added the ``portgroup_uuid`` response field. + +API microversion 1.34 added the ``physical_network`` response field. Normal response code: 200 @@ -240,6 +253,11 @@ Update a Port Update a Port. +API microversion 1.19 added the ``pxe_enabled`` and ``local_link_connection`` +fields. + +API microversion 1.24 added the ``portgroup_uuid`` field. + API microversion 1.34 added the ``physical_network`` field. Normal response code: 200