From bca44bcefc6fc67d50d4fd63a948726a35c54f5b Mon Sep 17 00:00:00 2001
From: Sam Betts <sam@code-smash.net>
Date: Wed, 2 Aug 2017 13:32:27 +0100
Subject: [PATCH] Switch API ref to use versionadded syntax throughout

Sphinx provides the versionadded syntax for indicating version related
changes in documentation, the OpenStack doc theme is designed to handle
this and render it nicely. This patch switches our inconsistent
references to API version related change in the API ref to use this
syntax so that it standardised through out the docs, and is more obvious
in the documentation itself.

Change-Id: Ied6f22deecebd71042d2230b81e057543db3d3f4
---
 api-ref/source/baremetal-api-v1-drivers.inc   |  28 ++--
 api-ref/source/baremetal-api-v1-misc.inc      |  18 ++-
 .../baremetal-api-v1-node-management.inc      |   6 +-
 .../baremetal-api-v1-nodes-portgroups.inc     |   6 +-
 .../source/baremetal-api-v1-nodes-ports.inc   |  27 ++--
 .../source/baremetal-api-v1-nodes-vifs.inc    |  10 +-
 .../source/baremetal-api-v1-nodes-volume.inc  |   6 +-
 api-ref/source/baremetal-api-v1-nodes.inc     | 116 +++++++-------
 .../baremetal-api-v1-portgroups-ports.inc     |  13 +-
 .../source/baremetal-api-v1-portgroups.inc    |  10 +-
 api-ref/source/baremetal-api-v1-ports.inc     |  80 +++++-----
 api-ref/source/baremetal-api-v1-volume.inc    |  10 +-
 api-ref/source/baremetal-api-versions.inc     |   7 +
 api-ref/source/parameters.yaml                | 142 +++++++-----------
 14 files changed, 242 insertions(+), 237 deletions(-)

diff --git a/api-ref/source/baremetal-api-v1-drivers.inc b/api-ref/source/baremetal-api-v1-drivers.inc
index 4e4d4b2289..439a043160 100644
--- a/api-ref/source/baremetal-api-v1-drivers.inc
+++ b/api-ref/source/baremetal-api-v1-drivers.inc
@@ -4,6 +4,9 @@
 Drivers (drivers)
 =================
 
+.. versionchanged:: 1.30
+  The REST API now also exposes information about *dynamic* drivers.
+
 Ironic has two types of drivers: *classic* drivers and *dynamic* drivers.
 
 A *classic* driver is a Python object containing all the logic to manage the
@@ -12,15 +15,13 @@ more ``ironic-conductor`` services. Each driver contains a pre-determined set
 of instantiated interfaces. Each type of interface (eg, ``power`` or ``boot``)
 performs a specific hardware function.
 
-As of API version 1.30, the REST API also exposes information about *dynamic*
-drivers. *Dynamic* drivers are supported via hardware types, which are Python
-classes enabled via entry points. Unlike *classic* drivers, which have
-pre-determined interfaces, a hardware type may support multiple types of
-interfaces. For example, the ``ipmi`` hardware type may support multiple
-methods for enabling node console. Which interface a node of a particular
-hardware type uses is determined at runtime. This collection of interfaces is
-called a *dynamic* driver. For more information about this, see the node API
-documentation.
+*Dynamic* drivers are supported via hardware types, which are Python classes
+enabled via entry points. Unlike *classic* drivers, which have pre-determined
+interfaces, a hardware type may support multiple types of interfaces. For
+example, the ``ipmi`` hardware type may support multiple methods for enabling
+node console. Which interface a node of a particular hardware type uses is
+determined at runtime. This collection of interfaces is called a *dynamic*
+driver. For more information about this, see the node API documentation.
 
 The REST API exposes the list of drivers and which ``ironic-conductor``
 processes have loaded that driver via the Driver resource (``/v1/drivers``
@@ -73,8 +74,9 @@ drivers supported by this Ironic service.
    - links: links
    - properties: driver_property_links
 
-Additionally, if the request has the "detail" URL parameter set to true, each
-driver will also include the following fields.
+.. versionchanged:: 1.30
+  If the request has the "detail" URL parameter set to true, each
+  driver will also include the following fields.
 
 .. rest_parameters:: parameters.yaml
 
@@ -201,14 +203,14 @@ The following example is returned from the ``agent_ipmitool`` driver.
 Show driver logical disk properties
 ===================================
 
+.. versionadded:: 1.12
+
 .. rest_method::  GET /v1/drivers/{driver_name}/raid/logical_disk_properties
 
 Show the required and optional parameters that ``driver_name`` expects to be
 supplied in the node's ``raid_config`` field, if a RAID configuration change is
 requested.
 
-This resource was added in API microversion 1.12.
-
 Normal response codes: 200
 
 Request
diff --git a/api-ref/source/baremetal-api-v1-misc.inc b/api-ref/source/baremetal-api-v1-misc.inc
index f86dcc3ecc..5bbc2e9be0 100644
--- a/api-ref/source/baremetal-api-v1-misc.inc
+++ b/api-ref/source/baremetal-api-v1-misc.inc
@@ -31,9 +31,11 @@ Agent Lookup
 
 .. rest_method:: GET /v1/lookup
 
-Beginning with the v1.22 API, a ``/lookup`` method is exposed at the root of
-the REST API. This should only be used by the ``ironic-python-agent`` ramdisk
-to retrieve required configuration data from the Bare Metal service.
+.. versionadded:: 1.22
+
+A ``/lookup`` method is exposed at the root of the REST API. This should only
+be used by the ``ironic-python-agent`` ramdisk to retrieve required
+configuration data from the Bare Metal service.
 
 By default, ``/v1/lookup`` will only match Nodes that are expected to be
 running the ``ironic-python-agent`` ramdisk (for instance, because the Bare
@@ -82,10 +84,12 @@ Agent Heartbeat
 
 .. rest_method:: POST /v1/heartbeat/{node_ident}
 
-Beginning with the v1.22 API, a ``/heartbeat`` method is exposed at the root of
-the REST API. This is used as a callback from within the ``ironic-python-agent``
-ramdisk, so that an active ramdisk may periodically contact the Bare Metal
-service and provide the current URL at which to contact the agent.
+.. versionadded:: 1.22
+
+A ``/heartbeat`` method is exposed at the root of the REST API. This is used
+as a callback from within the ``ironic-python-agent`` ramdisk, so that an
+active ramdisk may periodically contact the Bare Metal service and provide
+the current URL at which to contact the agent.
 
 Normal response codes: 202
 
diff --git a/api-ref/source/baremetal-api-v1-node-management.inc b/api-ref/source/baremetal-api-v1-node-management.inc
index 38341fff7b..c443a73ea1 100644
--- a/api-ref/source/baremetal-api-v1-node-management.inc
+++ b/api-ref/source/baremetal-api-v1-node-management.inc
@@ -228,6 +228,8 @@ Inject NMI (Non-Masking Interrupts)
 
 .. rest_method:: PUT /v1/nodes/{node_ident}/management/inject_nmi
 
+.. versionadded:: 1.29
+
 Inject NMI (Non-Masking Interrupts) for the given Node. This feature
 can be used for hardware diagnostics, and actual support depends on a
 driver.
@@ -365,6 +367,8 @@ Set RAID Config
 
 .. rest_method:: PUT /v1/nodes/{node_ident}/states/raid
 
+.. versionadded:: 1.12
+
 Store the supplied configuration on the Node's ``target_raid_config`` property.
 This property must be structured JSON, and will be validated by the driver upon receipt. The request
 schema is defined in the `documentation for the RAID feature <http://docs.openstack.org/ironic/latest/admin/raid.html>`_
@@ -372,8 +376,6 @@ schema is defined in the `documentation for the RAID feature <http://docs.openst
 .. note:: Calling this API only stores the requested configuration; it will be applied the next time
   that the Node transitions through the ``cleaning`` phase.
 
-Added in API microversion: 1.12
-
 Normal response code: 204
 
 .. TODO: add more description, response code, sample response
diff --git a/api-ref/source/baremetal-api-v1-nodes-portgroups.inc b/api-ref/source/baremetal-api-v1-nodes-portgroups.inc
index ca96fc4e2c..fc9cfbc2b3 100644
--- a/api-ref/source/baremetal-api-v1-nodes-portgroups.inc
+++ b/api-ref/source/baremetal-api-v1-nodes-portgroups.inc
@@ -4,6 +4,8 @@
 Listing Portgroups by Node (nodes, portgroups)
 ==============================================
 
+.. versionadded:: 1.24
+
 Given a Node identifier (``uuid`` or ``name``), the API exposes the list of,
 and details of, all Portgroups associated with that Node.
 
@@ -11,10 +13,6 @@ These endpoints do not allow modification of the Portgroups; that should be
 done by accessing the Portgroup resources under the ``/v1/portgroups``
 endpoint.
 
-Portgroup resource was added in API microversion 1.24, if using older
-version, all the requests return ``Not Found (404)`` error code.
-
-
 List Portgroups by Node
 =======================
 
diff --git a/api-ref/source/baremetal-api-v1-nodes-ports.inc b/api-ref/source/baremetal-api-v1-nodes-ports.inc
index 5e4f74778e..40a7d5e9d7 100644
--- a/api-ref/source/baremetal-api-v1-nodes-ports.inc
+++ b/api-ref/source/baremetal-api-v1-nodes-ports.inc
@@ -18,16 +18,19 @@ 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.
+.. versionadded:: 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.
+.. versionadded:: 1.19
+  Added the ``pxe_enabled`` and ``local_link_connection`` fields.
 
-API microversion 1.24 added the ``portgroup_uuid`` field.
+.. versionadded:: 1.24
+  Added the ``portgroup_uuid`` field.
 
-API microversion 1.34 added the ``physical_network`` field.
+.. versionadded:: 1.34
+  Added the ``physical_network`` field.
 
 Normal response code: 200
 
@@ -67,12 +70,14 @@ 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.
+.. versionadded:: 1.19
+  Added the ``pxe_enabled`` and ``local_link_connection`` fields.
 
-API microversion 1.24 added the ``portgroup_uuid`` field.
+.. versionadded:: 1.24
+  Added the ``portgroup_uuid`` field.
 
-API microversion 1.34 added the ``physical_network`` field.
+.. versionadded:: 1.34
+  Added the ``physical_network`` field.
 
 Normal response code: 200
 
diff --git a/api-ref/source/baremetal-api-v1-nodes-vifs.inc b/api-ref/source/baremetal-api-v1-nodes-vifs.inc
index 3d0bbfe674..07b4f9ef2d 100644
--- a/api-ref/source/baremetal-api-v1-nodes-vifs.inc
+++ b/api-ref/source/baremetal-api-v1-nodes-vifs.inc
@@ -4,10 +4,12 @@
 VIFs (Virtual Interfaces) of nodes
 ==================================
 
-Starting with API version 1.28 attaching and detaching VIFs (Virtual Interfaces)
-to or from a node are done via the ``v1/nodes/{node_ident}/vifs`` endpoint. Attaching
-a VIF to a node means that a VIF will be mapped to a free port or port group of
-the specified node.
+.. versionadded:: 1.28
+
+Attaching and detaching VIFs (Virtual Interfaces) to or from a node are done
+via the ``v1/nodes/{node_ident}/vifs`` endpoint. Attaching a VIF to a node
+means that a VIF will be mapped to a free port or port group of the specified
+node.
 
 List attached VIFs of a Node
 ============================
diff --git a/api-ref/source/baremetal-api-v1-nodes-volume.inc b/api-ref/source/baremetal-api-v1-nodes-volume.inc
index 4840fe0317..d170fa053f 100644
--- a/api-ref/source/baremetal-api-v1-nodes-volume.inc
+++ b/api-ref/source/baremetal-api-v1-nodes-volume.inc
@@ -4,6 +4,8 @@
 Listing Volume resources by Node (nodes, volume)
 ================================================
 
+.. versionadded:: 1.32
+
 Given a Node identifier (``uuid`` or ``name``), the API exposes the list of,
 and details of, all Volume resources associated with that Node.
 
@@ -11,10 +13,6 @@ These endpoints do not allow modification of the Volume connectors and Volume
 targets; that should be done by accessing the Volume resources under the
 ``/v1/volume/connectors`` and ``/v1/volume/targets`` endpoint.
 
-Volume resource was added in API microversion 1.32. If using an older
-version, all the requests return ``Not Found (404)`` error code.
-
-
 List Links of Volume Resources by Node
 ======================================
 
diff --git a/api-ref/source/baremetal-api-v1-nodes.inc b/api-ref/source/baremetal-api-v1-nodes.inc
index 5f712a0b11..f4c7a83a69 100644
--- a/api-ref/source/baremetal-api-v1-nodes.inc
+++ b/api-ref/source/baremetal-api-v1-nodes.inc
@@ -12,10 +12,11 @@ A Node is the canonical representation of a discretely allocatable server,
 capable of running an Operating System. Each Node must be associated with a
 ``driver``; this informs Ironic what protocol to use when managing the Node.
 
-Beginning with API microversion 1.6, a Node may be referenced both by its UUID
-and by a unique human-readable "name" in any request. Throughout this
-documentation, this is referred to as the ``node_ident``. Responses clearly
-indicate whether a given field is a ``uuid`` or a ``name``.
+.. versionchanged:: 1.6
+  A Node may be referenced both by its UUID and by a unique human-readable
+  "name" in any request. Throughout this documentation, this is referred to as
+  the ``node_ident``. Responses clearly indicate whether a given field is a
+  ``uuid`` or a ``name``.
 
 Depending on the Roles assigned to the authenticated OpenStack User, and upon
 the configuration of the Bare Metal service, API responses may change. For
@@ -34,22 +35,52 @@ This method requires that a ``driver`` be supplied in the request body.  Most
 subresources of a Node (eg, ``properties``, ``driver_info``, etc) may be
 supplied when the Node is created, or the resource may be updated later.
 
-If the specified driver is a dynamic driver (available from API microversion
-1.31), then all the interfaces (boot_interface, deploy_interface, etc.)
-will be set to the default interface for that driver unless another enabled
-interface is specified in the creation request.
+.. versionadded:: 1.2
+  Added ``available`` state name, which replaced ``None`` as the status of an
+  unprovisioned Node. All clients should be updated to use the new
+  ``available`` state name.  Nodes in the ``available`` state may have
+  workloads provisioned on them; they are "available" for use.
 
-API microversion 1.2 introduced the new ``available`` state name, which replaced
-``None`` as the status of an unprovisioned Node. All clients should be updated to
-use the new ``available`` state name.
+.. versionadded:: 1.5
+  Introduced the ``name`` field.
 
-Nodes in the ``available`` state may have workloads provisioned on them; they are
-"available" for use.
+.. versionadded:: 1.7
+  Introduced the ``clean_step`` field.
 
-API microversion 1.11 changed the default initial state of newly-created Nodes
-from ``available`` to ``enroll``. This provides users a workflow to verify the
-manageability of a Node and perform necessary operational functions (eg, building
-a RAID array) before making the Node available for provisioning.
+.. versionchanged:: 1.11
+  The default initial state of newly-created Nodes from ``available`` to
+  ``enroll``. This provides users a workflow to verify the manageability of a
+  Node and perform necessary operational functions (eg, building a RAID array)
+  before making the Node available for provisioning.
+
+.. versionadded:: 1.12
+  Introduced support for the ``raid_config`` and ``target_raid_config`` fields.
+
+.. versionadded:: 1.20
+  Introduced the ``network_interface`` field. If this field is not supplied
+  when creating the Node, the default value will be used.
+
+.. versionadded:: 1.21
+  Introduced the ``resource_class`` field, which may be used to store a
+  resource designation for the proposed OpenStack Placement Engine. This field
+  has no effect within Ironic.
+
+.. versionadded:: 1.31
+  Introduced the ``boot_interface``, ``deploy_interface``,
+  ``management_interface``, ``power_interface``, ``inspect_interface``,
+  ``console_interface``, ``vendor_interface`` and ``raid_interface`` fields. If
+  any of these fields are not supplied when creating the Node, their default
+  value will be used.
+
+.. versionchanged:: 1.31
+  If the specified driver is a dynamic driver, then all the interfaces
+  (boot_interface, deploy_interface, etc.) will be set to the default interface
+  for that driver unless another enabled interface is specified in the creation
+  request.
+
+.. versionadded:: 1.33
+  Introduced the ``storage_interface`` field. If this field is not supplied
+  when creating the Node, the default value will be used.
 
 Normal response codes: 201
 
@@ -79,32 +110,6 @@ The response will contain the complete Node record, with the supplied data,
 and any defaults added for non-specified fields. Most fields default to "null"
 or "".
 
-API microversion 1.5 introduced the ``name`` field.
-
-API microversion 1.7 introduced the ``clean_step`` field`
-
-API microversion 1.12 introduced support for the ``raid_config`` and
-``target_raid_config`` fields.
-
-API microversion 1.20 introduced the ``network_interface`` field. If this field
-is not supplied when creating the Node, the default value will be used.
-
-API microversion 1.21 introduced the ``resource_class`` field, which may be
-used to store a resource designation for the proposed OpenStack Placement
-Engine. This field has no effect within Ironic.
-
-API microversion 1.24 introduced the ``/nodes/{node_ident}/portgroups``
-endpoint.
-
-API microversion 1.31 introduced all of the ``*_interface`` fields
-(boot_interface, deploy_interface, etc.), with the exception of the
-network_interface field, which was introduced in API microversion 1.20. If this
-field is not supplied when creating the Node, the default value will be used.
-
-.. versionadded:: 1.33
-   The ``storage_interface`` field was introduced. If this field is not supplied when creating
-   the Node, the default value will be used.
-
 The list and example below are representative of the response as of API
 microversion 1.33.
 
@@ -166,18 +171,22 @@ each Node. Some filtering is possible by passing in flags with the request.
 By default, this query will return the name, uuid, instance uuid, power state,
 provision state, and maintenance setting for each Node.
 
-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.
+.. versionadded:: 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.9 added the ``provision_state`` Request parameter, allowing
-the list of returned Nodes to be filtered by their current state.
+.. versionadded:: 1.9
+  Added the ``provision_state`` Request parameter, allowing the list of
+  returned Nodes to be filtered by their current state.
 
-API microversion 1.16 added the ``driver`` Request parameter, allowing
-the list of returned Nodes to be filtered by their driver name.
+.. versionadded:: 1.16
+  Added the ``driver`` Request parameter, allowing the list of returned Nodes
+  to be filtered by their driver name.
 
-API microversion 1.21 added the ``resource_class`` Request parameter,
-allowing the list of returned Nodes to be filtered by this field.
+.. versionadded:: 1.21
+  Added the ``resource_class`` Request parameter, allowing the list of returned
+  Nodes to be filtered by this field.
 
 Normal response codes: 200
 
@@ -381,7 +390,8 @@ Updates the information stored about a Node.
 Note that this endpoint can not be used to request state changes, which are
 managed through sub-resources.
 
-API microversion 1.25 introduced the ability to unset a node's chassis UUID.
+.. versionadded:: 1.25
+  Introduced the ability to unset a node's chassis UUID.
 
 Normal response codes: 200
 
diff --git a/api-ref/source/baremetal-api-v1-portgroups-ports.inc b/api-ref/source/baremetal-api-v1-portgroups-ports.inc
index 72175cf66e..1f4f2ed367 100644
--- a/api-ref/source/baremetal-api-v1-portgroups-ports.inc
+++ b/api-ref/source/baremetal-api-v1-portgroups-ports.inc
@@ -4,17 +4,14 @@
 Listing Ports by Portgroup (portgroup, ports)
 =============================================
 
+.. versionadded:: 1.24
+
 Given a Portgroup identifier (``uuid`` or ``name``), the API exposes the list
 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.
 
-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
 =======================
 
@@ -25,7 +22,8 @@ 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.
+.. versionadded:: 1.34
+  Added the ``physical_network`` field.
 
 Normal response code: 200
 
@@ -65,7 +63,8 @@ List detailed Ports by Portgroup
 
 Return a detailed list of bare metal Ports associated with ``portgroup_ident``.
 
-API microversion 1.34 added the ``physical_network`` field.
+.. versionadded:: 1.34
+  Added the ``physical_network`` field.
 
 Normal response code: 200
 
diff --git a/api-ref/source/baremetal-api-v1-portgroups.inc b/api-ref/source/baremetal-api-v1-portgroups.inc
index 031450c95d..338c903e5e 100644
--- a/api-ref/source/baremetal-api-v1-portgroups.inc
+++ b/api-ref/source/baremetal-api-v1-portgroups.inc
@@ -4,10 +4,12 @@
 Portgroups (portgroups)
 =======================
 
-Starting with API version 1.23 ports can be combined into portgroups to support
-static link aggregation group (LAG) or multi-chassis link aggregation group
-(MLAG) configurations. Listing, Searching, Creating, Updating, and Deleting of
-bare metal Portgroup resources are done through the ``v1/portgroups`` resource.
+.. versionadded:: 1.23
+
+Ports can be combined into portgroups to support static link aggregation group
+(LAG) or multi-chassis link aggregation group (MLAG) configurations. Listing,
+Searching, Creating, Updating, and Deleting of bare metal Portgroup resources
+are done through the ``v1/portgroups`` resource.
 
 All Portgroups must be associated with a Node when created. This association
 can be changed, though the request may be rejected if either the current
diff --git a/api-ref/source/baremetal-api-v1-ports.inc b/api-ref/source/baremetal-api-v1-ports.inc
index bc9d65203e..88e08a53a4 100644
--- a/api-ref/source/baremetal-api-v1-ports.inc
+++ b/api-ref/source/baremetal-api-v1-ports.inc
@@ -24,20 +24,23 @@ some parameters with the request.
 
 By default, this query will return the uuid and address for each Port.
 
-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.
+.. versionadded:: 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,
-rather than the default set.
+.. versionadded:: 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.
+.. versionadded:: 1.19
+  Added the ``pxe_enabled`` and ``local_link_connection`` fields.
 
-API microversion 1.24 added the ``portgroup_uuid`` field.
+.. versionadded:: 1.24
+  Added the ``portgroup_uuid`` field.
 
-API microversion 1.34 added the ``physical_network`` field.
+.. versionadded:: 1.34
+  Added the ``physical_network`` field.
 
 Normal response code: 200
 
@@ -82,13 +85,15 @@ Creates a new Port resource.
 This method requires a Node UUID and the physical hardware address for the Port
 (MAC address in most cases).
 
-API microversion 1.19 added the ``pxe_enabled`` and ``local_link_connection``
-request and response fields.
+.. versionadded:: 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.
+.. versionadded:: 1.24
+  Added the ``portgroup_uuid`` request and response fields.
 
-API microversion 1.34 added the ``physical_network`` request and response
-fields.
+.. versionadded:: 1.34
+  Added the ``physical_network`` request and response fields.
 
 Normal response code: 201
 
@@ -141,17 +146,19 @@ List Detailed Ports
 
 Return a list of bare metal Ports, with detailed information.
 
-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.
+.. versionadded:: 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.19 added the ``pxe_enabled`` and ``local_link_connection``
-response fields.
+.. versionadded:: 1.19
+  Added the ``pxe_enabled`` and ``local_link_connection`` response fields.
 
-API microversion 1.24 added the ``portgroup`` query parameter and
-``portgroup_uuid`` response field.
+.. versionadded:: 1.24
+  Added the ``portgroup`` query parameter and ``portgroup_uuid`` response
+  field.
 
-API microversion 1.34 added the ``physical_network`` response field.
+.. versionadded:: 1.34
+  Added the ``physical_network`` response field.
 
 Normal response code: 200
 
@@ -201,16 +208,19 @@ 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,
-rather than the default set.
+.. versionadded:: 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``
-response fields.
+.. versionadded:: 1.19
+  Added the ``pxe_enabled`` and ``local_link_connection`` response fields.
 
-API microversion 1.24 added the ``portgroup_uuid`` response field.
+.. versionadded:: 1.24
+  Added the ``portgroup_uuid`` response field.
 
-API microversion 1.34 added the ``physical_network`` response field.
+.. versionadded:: 1.34
+  Added the ``physical_network`` response field.
 
 Normal response code: 200
 
@@ -253,12 +263,14 @@ Update a Port
 
 Update a Port.
 
-API microversion 1.19 added the ``pxe_enabled`` and ``local_link_connection``
-fields.
+.. versionadded:: 1.19
+  Added the ``pxe_enabled`` and ``local_link_connection`` fields.
 
-API microversion 1.24 added the ``portgroup_uuid`` field.
+.. versionadded:: 1.24
+  Added the ``portgroup_uuid`` field.
 
-API microversion 1.34 added the ``physical_network`` field.
+.. versionadded:: 1.34
+  Added the ``physical_network`` field.
 
 Normal response code: 200
 
diff --git a/api-ref/source/baremetal-api-v1-volume.inc b/api-ref/source/baremetal-api-v1-volume.inc
index 01fdf8ae75..721b39a87a 100644
--- a/api-ref/source/baremetal-api-v1-volume.inc
+++ b/api-ref/source/baremetal-api-v1-volume.inc
@@ -4,10 +4,12 @@
 Volume (volume)
 ===============
 
-Since API version 1.32, information for connecting remote volumes to a node
-can be associated with a Node. There are two types of resources, Volume
-connectors and Volume targets. Volume connectors contain initiator information
-of Nodes. Volume targets contain target information of remote volumes.
+.. versionadded:: 1.32
+
+Information for connecting remote volumes to a node can be associated with a
+Node. There are two types of resources, Volume connectors and Volume targets.
+Volume connectors contain initiator information of Nodes. Volume targets
+contain target information of remote volumes.
 
 Listing, Searching, Creating, Updating, and Deleting of Volume connector
 resources are done through the ``v1/volume/connectors`` resource. The same
diff --git a/api-ref/source/baremetal-api-versions.inc b/api-ref/source/baremetal-api-versions.inc
index 11b5ec769b..dc580811c3 100644
--- a/api-ref/source/baremetal-api-versions.inc
+++ b/api-ref/source/baremetal-api-versions.inc
@@ -22,6 +22,13 @@ with every request; in the absence of this header, each request is treated
 as though coming from an older pre-Kilo client. This was done to preserve
 backwards compatibility as we introduced new features in the server.
 
+If you try to use a feature with an API version older than when that feature
+was introduced the ironic service will respond as would before that feature
+existed. For example if a new API URL was added, and you try to make a request
+with an older API version, then you will get a ``Not Found (404)`` error, or if
+a new field was added to an existing API and you request an older API version
+then you will get an ``Invalid Parameter`` response.
+
 List API versions
 =================
 
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 7fd97b170c..bf181db420 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -70,7 +70,7 @@ port_ident:
   type: string
 portgroup_ident:
   description: |
-    The UUID or Name of the portgroup. Added in API microversion 1.23.
+    The UUID or Name of the portgroup.
   in: path
   required: true
   type: string
@@ -107,14 +107,13 @@ detail:
 driver_detail:
   description: |
     Whether to show detailed information about the drivers (e.g. the
-    "boot_interface" field). Added in API microversion 1.30.
+    "boot_interface" field).
   in: query
   required: false
   type: boolean
 driver_type:
   description: |
-    Only list drivers of this type. Options are "classic" or "dynamic". Added
-    in API microversion 1.30.
+    Only list drivers of this type. Options are "classic" or "dynamic".
   in: query
   required: false
   type: string
@@ -233,7 +232,6 @@ r_port_portgroup_ident:
   description: |
     Filter the list of returned Ports, and only return the ones associated
     with this specific Portgroup (name or UUID), or an empty set if not found.
-    Added in API microversion 1.24.
   in: query
   required: false
   type: string
@@ -241,7 +239,7 @@ r_portgroup_address:
   description: |
     Filter the list of returned Portgroups, and only return the ones with the
     specified physical hardware address, typically MAC, or an empty set if not
-    found. Added in API microversion 1.23.
+    found.
   in: query
   required: false
   type: string
@@ -249,7 +247,6 @@ r_portgroup_node_ident:
   description: |
     Filter the list of returned Portgroups, and only return the ones associated
     with this specific node (name or UUID), or an empty set if not found.
-    Added in API microversion 1.23.
   in: query
   required: false
   type: string
@@ -263,7 +260,7 @@ r_provision_state:
 r_resource_class:
   description: |
     Filter the list of returned nodes, and only return the ones with the
-    specified resource class. Introduced in API version 1.21.
+    specified resource class.
   in: query
   required: false
   type: string
@@ -271,7 +268,7 @@ r_volume_connector_node_ident:
   description: |
     Filter the list of returned Volume connectors, and only return the ones
     associated with this specific node (name or UUID), or an empty set if not
-    found. Added in API microversion 1.32.
+    found.
   in: query
   required: false
   type: string
@@ -279,7 +276,7 @@ r_volume_target_node_ident:
   description: |
     Filter the list of returned Volume targets, and only return the ones
     associated with this specific node (name or UUID), or an empty set if not
-    found. Added in API microversion 1.32.
+    found.
   in: query
   required: false
   type: string
@@ -332,7 +329,7 @@ boot_device:
   type: string
 boot_interface:
   description: |
-    The boot interface for a Node, e.g. "pxe". Added in API microversion 1.31.
+    The boot interface for a Node, e.g. "pxe".
   in: body
   required: true
   type: string
@@ -379,8 +376,7 @@ console_enabled:
   type: boolean
 console_interface:
   description: |
-    The console interface for a node, e.g. "no-console". Added in API
-    microversion 1.31.
+    The console interface for a node, e.g. "no-console".
   in: body
   required: true
   type: string
@@ -394,86 +390,76 @@ created_at:
 default_boot_interface:
   description: |
     The default boot interface used for a node with a dynamic driver, if no
-    boot interface is specified for the node. Added in API microversion 1.30.
+    boot interface is specified for the node.
   in: body
   required: true
   type: string
 default_console_interface:
   description: |
     The default console interface used for a node with a dynamic driver, if no
-    console interface is specified for the node. Added in API microversion
-    1.30.
+    console interface is specified for the node.
   in: body
   required: true
   type: string
 default_deploy_interface:
   description: |
     The default deploy interface used for a node with a dynamic driver, if no
-    deploy interface is specified for the node. Added in API microversion
-    1.30.
+    deploy interface is specified for the node.
   in: body
   required: true
   type: string
 default_inspect_interface:
   description: |
     The default inspection interface used for a node with a dynamic driver, if
-    no inspection interface is specified for the node. Added in API
-    microversion 1.30.
+    no inspection interface is specified for the node.
   in: body
   required: true
   type: string
 default_management_interface:
   description: |
     The default management interface used for a node with a dynamic driver, if
-    no management interface is specified for the node. Added in API
-    microversion 1.30.
+    no management interface is specified for the node.
   in: body
   required: true
   type: string
 default_network_interface:
   description: |
     The default network interface used for a node with a dynamic driver, if
-    no network interface is specified for the node. Added in API
-    microversion 1.30.
+    no network interface is specified for the node.
   in: body
   required: true
   type: string
 default_power_interface:
   description: |
     The default power interface used for a node with a dynamic driver, if
-    no power interface is specified for the node. Added in API
-    microversion 1.30.
+    no power interface is specified for the node.
   in: body
   required: true
   type: string
 default_raid_interface:
   description: |
     The default RAID interface used for a node with a dynamic driver, if
-    no RAID interface is specified for the node. Added in API
-    microversion 1.30.
+    no RAID interface is specified for the node.
   in: body
   required: true
   type: string
 default_storage_interface:
   description: |
     The default storage interface used for a node with a dynamic driver, if
-    no storage interface is specified for the node. Added in API
-    microversion 1.33.
+    no storage interface is specified for the node.
   in: body
   required: true
   type: string
 default_vendor_interface:
   description: |
     The default vendor interface used for a node with a dynamic driver, if
-    no vendor interface is specified for the node. Added in API
-    microversion 1.30.
+    no vendor interface is specified for the node.
   in: body
   required: true
   type: string
 deploy_interface:
   description: |
-    The deploy interface for a node, e.g. "iscsi". Added in API microversion
-    1.31.
+    The deploy interface for a node, e.g. "iscsi".
   in: body
   required: true
   type: string
@@ -504,7 +490,7 @@ driver_name:
   type: string
 driver_property_links:
   description: |
-    A list of links to driver properties. Added in API microversion 1.14.
+    A list of links to driver properties.
   in: body
   required: true
   type: array
@@ -516,71 +502,61 @@ drivers:
   type: array
 enabled_boot_interfaces:
   description: |
-    The enabled boot interfaces for this driver. Added in API microversion
-    1.30.
+    The enabled boot interfaces for this driver.
   in: body
   required: true
   type: list
 enabled_console_interfaces:
   description: |
-    The enabled console interfaces for this driver. Added in API microversion
-    1.30.
+    The enabled console interfaces for this driver.
   in: body
   required: true
   type: list
 enabled_deploy_interfaces:
   description: |
-    The enabled deploy interfaces for this driver. Added in API microversion
-    1.30.
+    The enabled deploy interfaces for this driver.
   in: body
   required: true
   type: list
 enabled_inspect_interfaces:
   description: |
-    The enabled inspection interfaces for this driver. Added in API
-    microversion 1.30.
+    The enabled inspection interfaces for this driver.
   in: body
   required: true
   type: list
 enabled_management_interfaces:
   description: |
-    The enabled management interfaces for this driver. Added in API
-    microversion 1.30.
+    The enabled management interfaces for this driver.
   in: body
   required: true
   type: list
 enabled_network_interfaces:
   description: |
-    The enabled network interfaces for this driver. Added in API microversion
-    1.30.
+    The enabled network interfaces for this driver.
   in: body
   required: true
   type: list
 enabled_power_interfaces:
   description: |
-    The enabled power interfaces for this driver. Added in API microversion
-    1.30.
+    The enabled power interfaces for this driver.
   in: body
   required: true
   type: list
 enabled_raid_interfaces:
   description: |
-    The enabled RAID interfaces for this driver. Added in API microversion
-    1.30.
+    The enabled RAID interfaces for this driver.
   in: body
   required: true
   type: list
 enabled_storage_interfaces:
   description: |
-    The enabled storage interfaces for this driver. Added in API microversion
-    1.33.
+    The enabled storage interfaces for this driver.
   in: body
   required: true
   type: list
 enabled_vendor_interfaces:
   description: |
-    The enabled vendor interfaces for this driver. Added in API microversion
-    1.30.
+    The enabled vendor interfaces for this driver.
   in: body
   required: true
   type: list
@@ -605,8 +581,7 @@ id:
   type: string
 inspect_interface:
   description: |
-    The interface used for node inspection, e.g. "no-inspect". Added in API
-    microversion 1.31.
+    The interface used for node inspection, e.g. "no-inspect".
   in: body
   required: true
   type: string
@@ -644,7 +619,6 @@ instance_uuid:
 internal_info:
   description: |
     Internal metadata set and stored by the Port. This field is read-only.
-    Added in API microversion 1.18.
   in: body
   required: true
   type: JSON
@@ -668,7 +642,6 @@ local_link_connection:
     in this field) and ``port_id`` (identifier of the physical port on the
     switch to which node's port is connected to) fields. ``switch_info`` is an
     optional string field to be used to store any vendor-specific information.
-    Added in API microversion 1.19.
   in: body
   required: true
   type: JSON
@@ -691,15 +664,13 @@ maintenance_reason:
   type: string
 management_interface:
   description: |
-    Interface for out-of-band node management, e.g. "ipmitool". Added in API
-    microversion 1.31.
+    Interface for out-of-band node management, e.g. "ipmitool".
   in: body
   required: true
   type: string
 n_portgroups:
   description: |
     Links to the collection of portgroups on this node.
-    Added in API microversion 1.24.
   in: body
   required: true
   type: array
@@ -725,13 +696,13 @@ n_states:
   type: array
 n_vifs:
   description: |
-    VIFs attached to this node. Added in API microversion 1.28.
+    VIFs attached to this node.
   in: body
   required: true
   type: array
 n_volume:
   description: |
-    Links to the volume resources. Added in API microversion 1.32.
+    Links to the volume resources.
   in: body
   required: true
   type: array
@@ -744,7 +715,7 @@ name:
 network_interface:
   description: |
     Which Network Interface provider to use when plumbing the network
-    connections for this Node. Added in API microversion v1.20
+    connections for this Node.
   in: body
   required: true
   type: string
@@ -758,7 +729,7 @@ next:
 node_name:
   description: |
     Human-readable identifier for the Node resource. May be undefined. Certain
-    words are reserved. Added in API microversion 1.5
+    words are reserved.
   in: body
   required: false
   type: string
@@ -770,7 +741,7 @@ node_uuid:
   type: string
 node_vif_ident:
   description: |
-    The UUID or name of the VIF. Added in API microversion 1.28.
+    The UUID or name of the VIF.
   in: body
   required: true
   type: string
@@ -816,15 +787,14 @@ persistent:
   type: boolean
 pg_ports:
   description: |
-    Links to the collection of ports belonging to this portgroup. Added in
-    API microversion 1.24.
+    Links to the collection of ports belonging to this portgroup.
   in: body
   required: true
   type: array
 physical_network:
   description: |
     The name of the physical network to which a port is connected. May be
-    empty. Added in API microversion 1.34.
+    empty.
   in: body
   required: true
   type: string
@@ -838,14 +808,13 @@ port_address:
 portgroup_address:
   description: |
     Physical hardware address of this Portgroup, typically the hardware
-    MAC address. Added in API microversion 1.23.
+    MAC address.
   in: body
   required: true
   type: string
 portgroup_internal_info:
   description: |
     Internal metadata set and stored by the Portgroup. This field is read-only.
-    Added in API microversion 1.23.
   in: body
   required: true
   type: JSON
@@ -855,33 +824,31 @@ portgroup_mode:
     https://www.kernel.org/doc/Documentation/networking/bonding.txt. If not
     specified in a request to create a port group, it will be set to the value
     of the ``[DEFAULT]default_portgroup_mode`` configuration option. When set,
-    can not be removed from the port group. Added in API microversion 1.26.
+    can not be removed from the port group.
   in: body
   required: true
   type: string
 portgroup_name:
   description: |
     Human-readable identifier for the Portgroup resource. May be undefined.
-    Added in API microversion 1.23.
   in: body
   required: false
   type: string
 portgroup_properties:
   description: |
     Key/value properties related to the port group's configuration.
-    Added in API microversion 1.26.
   in: body
   required: true
   type: JSON
 portgroup_uuid:
   description: |
-    UUID of the Portgroup this resource belongs to. Added in API microversion 1.23.
+    UUID of the Portgroup this resource belongs to.
   in: body
   required: true
   type: string
 portgroups:
   description: |
-    A collection of Portgroup resources. Added in API microversion 1.23.
+    A collection of Portgroup resources.
   in: body
   required: true
   type: array
@@ -894,7 +861,6 @@ ports:
 power_interface:
   description: |
     Interface used for performing power actions on the node, e.g. "ipmitool".
-    Added in API microversion 1.31.
   in: body
   required: true
   type: string
@@ -907,7 +873,7 @@ power_state:
   type: string
 power_timeout:
   description: |
-    Timeout for a power state transition. Added in API microversion 1.27.
+    Timeout for a power state transition.
   in: body
   required: false
   type: integer
@@ -933,8 +899,7 @@ provision_updated_at:
   type: string
 pxe_enabled:
   description: |
-    Indicates whether PXE is enabled or disabled on the Port. Added in API
-    microversion 1.19.
+    Indicates whether PXE is enabled or disabled on the Port.
   in: body
   required: true
   type: boolean
@@ -953,8 +918,7 @@ raid_config:
   type: JSON
 raid_interface:
   description: |
-    Interface used for configuring RAID on this node, e.g. "no-raid". Added in
-    API microversion 1.31.
+    Interface used for configuring RAID on this node, e.g. "no-raid".
   in: body
   required: true
   type: string
@@ -982,7 +946,7 @@ resource_class:
   description: |
     A string which can be used by external schedulers to identify this Node as
     a unit of a specific type of resource. This will be used by the openstack
-    Placement Engine in a future release. Added in API microversion 1.21.
+    Placement Engine in a future release.
   in: body
   required: true
   type: string
@@ -995,14 +959,14 @@ response_driver_type:
 standalone_ports_supported:
   description: |
     Indicates whether ports that are members of this portgroup can be
-    used as stand-alone ports. Added in API microversion 1.23.
+    used as stand-alone ports.
   in: body
   required: true
   type: boolean
 storage_interface:
   description: |
     Interface used for attaching and detaching volumes on this node, e.g.
-    "cinder". Added in API microversion 1.33.
+    "cinder".
   in: body
   required: true
   type: string
@@ -1015,9 +979,8 @@ supported_boot_devices:
 target_power_state:
   description: |
     If a power state transition has been requested, this field represents the
-    requested (ie, "target") state either "power on", "power off", or "rebooting".
-    Added new target power states "soft power off" and "soft rebooting" in API
-    microversion 1.27.
+    requested (ie, "target") state either "power on", "power off", "rebooting",
+    "soft power off" or "soft rebooting".
   in: body
   required: true
   type: string
@@ -1100,7 +1063,6 @@ v_raid:
 vendor_interface:
   description: |
     Interface for vendor-specific functionality on this node, e.g. "no-vendor".
-    Added in API microversion 1.31.
   in: body
   required: true
   type: string