Update the api-ref documentation for Root and Nodes

This updates the API root documentation, which was non-existent,
and the Node documentation significantly, replacing many of the samples
and adding more verbiage to each property.

It's not perfect, but this is vastly more correct than the current docs.

Change-Id: Iaeb1c80ac0655fc0d73fa495ed43e3c02b345495

29 files changed, 1766 insertions, 376 deletions

diff --git a/api-ref/source/baremetal-api-v1-chassis.inc b/api-ref/source/baremetal-api-v1-chassis.inc
index 46a1b7834..54b4ddbc1 100644
--- a/api-ref/source/baremetal-api-v1-chassis.inc
+++ b/api-ref/source/baremetal-api-v1-chassis.inc
@@ -4,7 +4,13 @@
 Chassis (chassis)
 =================
 
-Chassis operations.
+The Chassis resource type was originally conceived as a means to group Node
+resources. Support for this continues to exist in the REST API, however, it is
+very minimal. The Chassis object does not provide any functionality today
+aside from a means to list a group of Nodes.
+
+Use of this resource is discouraged, and may be deprecated and removed in a
+future release.
 
 
 List chassis with details
@@ -14,11 +20,9 @@ List chassis with details
 
 Lists all chassis with details.
 
-
 Normal response codes: 200
 Error response codes:413,405,404,403,401,400,503,
 
-
 Request
 -------
 
@@ -29,7 +33,6 @@ Request
    - sort_dir: sort_dir
    - sort_key: sort_key
 
-
 Response Parameters
 -------------------
 
@@ -40,8 +43,6 @@ Response Parameters
    - description: description
    - extra: extra
 
-
-
 Response Example
 ----------------
 
@@ -49,15 +50,6 @@ Response Example
    :language: javascript
 
 
-
-
-
-
-
-
-
-
-
 Show chassis details
 ====================
 
@@ -65,11 +57,9 @@ Show chassis details
 
 Shows details for a chassis.
 
-
 Normal response codes: 200
 Error response codes:413,405,404,403,401,400,503,
 
-
 Request
 -------
 
@@ -77,7 +67,6 @@ Request
 
    - fields: fields
 
-
 Response Parameters
 -------------------
 
@@ -88,24 +77,12 @@ Response Parameters
    - description: description
    - extra: extra
 
-
-
 Response Example
 ----------------
 
 .. literalinclude:: samples/chassis-show-response.json
    :language: javascript
 
-
-
-
-
-
-
-
-
-
-
 Update chassis
 ==============
 
@@ -113,11 +90,9 @@ Update chassis
 
 Updates a chassis.
 
-
 Normal response codes: 200
 Error response codes:413,415,405,404,403,401,400,503,409,
 
-
 Request
 -------
 
@@ -133,8 +108,6 @@ Request Example
 .. literalinclude:: samples/chassis-update-request.json
    :language: javascript
 
-
-
 Response Parameters
 -------------------
 
@@ -149,8 +122,6 @@ Response Parameters
    - nodes: nodes
    - uuid: uuid
 
-
-
 Response Example
 ----------------
 
@@ -158,17 +129,6 @@ Response Example
    :language: javascript
 
 
-
-
-
-
-
-
-
-
-
-
-
 Delete chassis
 ==============
 
@@ -178,25 +138,9 @@ Deletes a chassis.
 
 Error response codes:204,413,415,405,404,403,401,400,503,409,
 
-
 Request
 -------
 
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
 Create chassis
 ==============
 
@@ -206,7 +150,6 @@ Creates a chassis.
 
 Error response codes:201,413,415,405,404,403,401,400,503,409,
 
-
 Request
 -------
 
@@ -222,8 +165,6 @@ Request Example
 .. literalinclude:: samples/chassis-create-request.json
    :language: javascript
 
-
-
 Response Parameters
 -------------------
 
@@ -237,19 +178,6 @@ Response Parameters
    - nodes: nodes
    - uuid: uuid
 
-
-
-
-
-
-
-
-
-
-
-
-
-
 List chassis
 ============
 
@@ -257,11 +185,9 @@ List chassis
 
 Lists all chassis.
 
-
 Normal response codes: 200
 Error response codes:413,405,404,403,401,400,503,
 
-
 Request
 -------
 
@@ -273,7 +199,6 @@ Request
    - sort_key: sort_key
    - fields: fields
 
-
 Response Parameters
 -------------------
 
@@ -284,20 +209,8 @@ Response Parameters
    - description: description
    - extra: extra
 
-
-
 Response Example
 ----------------
 
 .. literalinclude:: samples/chassis-list-response.json
    :language: javascript
-
-
-
-
-
-
-
-
-
-
diff --git a/api-ref/source/baremetal-api-v1-node-management.inc b/api-ref/source/baremetal-api-v1-node-management.inc
new file mode 100644
index 000000000..289ab743a
--- /dev/null
+++ b/api-ref/source/baremetal-api-v1-node-management.inc
@@ -0,0 +1,393 @@
+.. -*- rst -*-
+
+=======================
+Node Management (nodes)
+=======================
+
+Nodes can be managed through several sub-resources.
+
+Maintenance mode can be set by the operator, with an optional "reason" stored
+by Ironic.
+
+The supplied ``driver_info`` can be validated to ensure that the selected
+``driver`` has all the information it requires to manage the Node.
+
+A Node can be rebooted, turned on, or turned off by requesting a change to its
+power state. This is handled asynchronously and tracked in the ``target_power_state``
+field after the request is received.
+
+A Node's boot device can be changed, and the set of supported boot devices
+can be queried.
+
+A request to change a Node's provision state is also tracked asynchronously;
+the ``target_provision_state`` represents the requested state. A Node
+may transition through several discrete ``provision_state`` steps before arriving
+at the requested state. This can vary between drivers and based on configuration.
+
+For example, a Node in the ``available`` state can have an instance deployed to it
+by requesting the provision state of ``active``. During this transition, the Node's
+``provision_state`` will temporarily be set to ``deploying``, and depending on the driver,
+it may also be ``wait call-back``. When the transitions are complete, ``target_provision_state``
+will be set to ``None`` and ``provision_state`` will be set to ``active```.
+To destroy the instance, request the provision state of ``delete``. During this
+transition, the Node may or may not go through a ``cleaning`` state,
+depending on the service configuration.
+
+
+Validate Node
+===============
+
+.. rest_method:: GET /v1/nodes/{node_ident}/validate
+
+Request that Ironic validate whether the Node's ``driver`` has enough information
+to manage the Node. This polls each ``interface`` on the driver, and returns
+the status of that ``interface`` as an element in the response. Note that each
+``driver`` may require different information to be supplied, and not all drivers
+support all interfaces.
+
+Normal response codes: 200
+
+.. TODO: add error codes
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - node_ident: node_ident
+
+Response
+--------
+
+Each element in the response will contain a "result" variable, which will have
+a value of "true" or "false", indicating that the interface either has or does
+not have sufficient information to function. A value of ``null`` indicates that
+the Node's driver does not support that interface.
+
+.. rest_parameters:: parameters.yaml
+
+  - power: v_power
+  - boot: v_boot
+  - deploy: v_deploy
+  - console: v_console
+  - management: v_management
+  - inspect: v_inspect
+  - raid: v_raid
+
+**Example node validation response:**
+
+.. literalinclude:: samples/node-validate-response.json
+   :language: javascript
+
+
+Set Maintenance Flag
+=============================
+
+.. rest_method:: PUT /v1/nodes/{node_ident}/maintenance
+
+Request that Ironic set the maintenance flag on the Node. This will disable
+certain automatic actions that the Node's driver may take, and remove
+the Node from Nova's available resource pool.
+
+Normal response code: 202
+
+.. TODO: Add link to user / operator documentation on the Maintenance flag
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - node_ident: node_ident
+    - reason: reason
+
+**Example request: mark a node for maintenance:**
+
+.. literalinclude:: samples/node-maintenance-request.json
+
+Clear Maintenance Flag
+==============================
+
+.. rest_method:: DELETE /v1/nodes/{node_ident}/maintenance
+
+The maintenance flag is unset by sending a DELETE request to this endpoint.
+If the request is accepted, Ironic will also clear the ``maintenance_reason``
+field.
+
+Normal response code: 202
+
+.. TODO: Add link to user / operator documentation on the Maintenance flag
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - node_ident: node_ident
+
+Set Boot Device
+===============
+
+.. rest_method:: PUT /v1/nodes/{node_ident}/management/boot_device
+
+Set the boot device for the given Node, and set it persistently or for one-time
+boot. The exact behaviour of this depends on the hardware driver.
+
+.. note:: In some drivers, eg.  the ``*_ipmitool`` family, this method initiates a synchronous call
+          to the hardware management device (BMC). It should be used with caution! This
+          is `a known bug <https://bugs.launchpad.net/ironic/+bug/1427923>`_.
+
+.. note:: Some drivers do not support one-time boot, and always set the boot device
+          persistently.
+
+Normal response code: 204
+
+.. TODO: add error codes
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - node_ident: node_ident
+    - boot_device: boot_device
+    - persistent: persistent
+
+**Example JSON request body to set boot device:**
+
+.. literalinclude:: samples/node-get-or-set-boot-device.json
+
+
+Get Boot Device
+===============
+
+.. rest_method:: GET /v1/nodes/{node_ident}/management/boot_device
+
+Get the current boot device for the given Node.
+
+.. note:: In some drivers, eg. the ``*_ipmitool`` family, this method initiates a synchronous call
+          to the hardware management device (BMC). It should be used with caution! This
+          is `a known bug <https://bugs.launchpad.net/ironic/+bug/1427923>`_.
+
+Normal response code: 200
+
+.. TODO: add error codes
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - node_ident: node_ident
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+    - boot_device: boot_device
+    - persistent: persistent
+
+**Example JSON response to get boot device:**
+
+.. literalinclude:: samples/node-get-or-set-boot-device.json
+
+
+Get Supported Boot Devices
+===========================
+
+.. rest_method:: GET /v1/nodes/{node_ident}/management/boot_device/supported
+
+Retrieve the acceptable set of supported boot devices for a specific Node.
+
+Normal response code: 200
+
+.. TODO: add error codes
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - node_ident: node_ident
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+    - supported_boot_devices: supported_boot_devices
+
+**Example response listing supported boot devices:**
+
+.. literalinclude:: samples/node-get-supported-boot-devices-response.json
+
+
+Node State Summary
+==================
+
+.. rest_method:: GET /v1/nodes/{node_ident}/states
+
+Get a summary of the Node's current power, provision, raid, and console status.
+
+Normal response code: 200
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - node_ident: node_ident
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+    - power_state: power_state
+    - target_power_state: target_power_state
+    - provision_state: provision_state
+    - target_provision_state: target_provision_state
+    - provision_updated_at: provision_updated_at
+    - last_error: last_error
+    - console_enabled: console_enabled
+    - raid_config: raid_config
+    - target_raid_config: target_raid_config
+
+**Example node state:**
+
+.. literalinclude:: samples/node-get-state-response.json
+
+
+Change Node Power State
+=======================
+
+.. rest_method:: PUT /v1/nodes/{node_ident}/states/power
+
+Request a change to the Node's power state.
+
+Normal response code: 202
+
+Error codes:
+    - 409 (NodeLocked, ClientError)
+    - 400 (InvalidState)
+    - 406 (NotAcceptable)
+    - 503 (NoFreeConductorWorkers)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - node_ident: node_ident
+    - target: power_state
+
+**Example request to power off a Node:**
+
+.. literalinclude:: samples/node-set-power-off.json
+
+
+Change Node Provision State
+===========================
+
+.. rest_method:: PUT /v1/nodes/{node_ident}/states/provision
+
+Request a change to the Node's provision state.
+
+Acceptable target states depend on the Node's current provision state. More
+detailed documentation of the Ironic State Machine is available
+`in the developer docs <http://docs.openstack.org/developer/ironic/dev/states.html>`_.
+
+Normal response code: 202
+
+Error codes:
+    - 409 (NodeLocked, ClientError)
+    - 400 (InvalidState, NodeInMaintenance)
+    - 406 (NotAcceptable)
+    - 503 (NoFreeConductorWorkers)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - node_ident: node_ident
+    - target: requested_provision_state
+    - configdrive: configdrive
+    - clean_steps: clean_steps
+
+**Example request to deploy a Node, using a configdrive served via local webserver:**
+
+.. literalinclude:: samples/node-set-active-state.json
+
+**Example request to clean a Node, with custom clean step:**
+
+.. literalinclude:: samples/node-set-clean-state.json
+
+
+Set RAID Config
+===============
+
+.. rest_method:: PUT /v1/nodes/{node_ident}/states/raid
+
+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/developer/ironic/deploy/raid.html>`_
+
+.. 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
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - node_ident: node_ident
+    - target_raid_config: target_raid_config
+
+**Example requested RAID config:**
+
+.. literalinclude:: samples/node-set-raid-request.json
+
+.. TODO: add more description, response code, sample response
+
+Get Console
+===========
+
+.. rest_method:: GET /v1/nodes/{node_ident}/states/console
+
+Get connection information about the console.
+
+.. TODO: add more description, response code, sample response
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - node_ident: node_ident
+
+.. TODO: add more description, response code, sample response
+
+Start/Stop Console
+===================
+
+.. rest_method:: PUT /v1/nodes/{node_ident}/states/console
+
+Start or stop the serial console.
+
+.. TODO: add more description, response code, sample response
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - node_ident: node_ident
+    - enabled: console_enabled
diff --git a/api-ref/source/baremetal-api-v1-node-passthru.inc b/api-ref/source/baremetal-api-v1-node-passthru.inc
new file mode 100644
index 000000000..a9efeb7f0
--- /dev/null
+++ b/api-ref/source/baremetal-api-v1-node-passthru.inc
@@ -0,0 +1,84 @@
+.. -*- rst -*-
+
+============================
+Node Vendor Passthru (nodes)
+============================
+
+Each driver MAY support vendor-specific extensions, called "passthru" methods.
+
+Internally, Ironic's driver API supports flexibly exposing functions via the
+common HTTP methods GET, PUT, POST, and DELETE. To call a passthru method,
+the query string must contain the name of the method, eg.
+``/vendor_passthru?method=reset_bmc``. The contents of the HTTP request are
+forwarded to the Node's driver and validated there.
+
+Ironic's REST API provides a means to discover these methods, but does not provide
+support, testing, or documentation for these endpoints. The Ironic development
+team does not guarantee any compatibility within these methods between releases,
+though we encourage driver authors to provide documentation and support for them.
+
+Besides the endpoints documented here, all other resources and endpoints
+under the heading ``vendor_passthru`` should be considered
+unsupported APIs, and could be changed without warning by the driver authors.
+
+
+List Methods
+============
+
+.. rest_method:: GET /v1/nodes/{node_ident}/vendor_passthru/methods
+
+Retrieve a list of the available vendor passthru methods for the given Node. The
+response will indicate which HTTP method(s) each vendor passthru method allows,
+whether the method call will be synchronous or asynchronous, and whether the
+response will include any attachment.
+
+Normal response code: 200
+
+.. TODO: add error codes
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - node_ident: node_ident
+
+Response
+--------
+
+**Example passthru methods listing:**
+
+.. literalinclude:: samples/node-vendor-passthru-response.json
+
+
+Call a Method
+=============
+
+.. rest_method:: METHOD /v1/nodes/{node_ident}/vendor_passthru?method={method_name}
+
+The HTTP METHOD may be one of GET, POST, PUT, DELETE, depending on the driver
+and method.
+
+This endpoint passes the request directly to the Node's hardware driver. The
+HTTP BODY must be parseable JSON, which will be converted to parameters passed
+to that function. Unparseable JSON, missing parameters, or excess parameters
+will cause the request to be rejected with an HTTP 400 error.
+
+Normal response code: 200 202
+
+.. TODO: add error codes
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - node_ident: node_ident
+    - method_name: method_name
+
+All other parameters should be passed in the BODY. Parameter list varies by method_name.
+
+Response
+--------
+
+Varies.
\ No newline at end of file
diff --git a/api-ref/source/baremetal-api-v1-nodes.inc b/api-ref/source/baremetal-api-v1-nodes.inc
index 03e35f490..6bb3f5c20 100644
--- a/api-ref/source/baremetal-api-v1-nodes.inc
+++ b/api-ref/source/baremetal-api-v1-nodes.inc
@@ -4,213 +4,373 @@
 Nodes (nodes)
 =============
 
+List, Searching, Creating, Updating, and Deleting of bare metal Node resources
+are done through the ``/v1/nodes`` resource. There are also several sub-resources,
+which allow further actions to be performed on a bare metal Node.
 
+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.
 
-
-Show node details
-=================
-
-.. rest_method::  GET /v1/nodes/{node_id}
-
-Shows details for a node.
-
-
-Normal response codes: 200
-Error response codes:413,405,404,403,401,400,503,
-
-
-Request
--------
-
-.. rest_parameters:: parameters.yaml
-
-   - node_id: node_id
-   - fields: fields
-
-
-
-
-Response Example
-----------------
-
-.. literalinclude:: samples/node-show-response.json
-   :language: javascript
-
-
-
-
-
-
+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``.
 
 
+Create Node
+===========
 
+.. rest_method::  POST /v1/nodes
 
+Creates a new Node resource.
 
-Update node
-===========
+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.
 
-.. rest_method::  PATCH /v1/nodes/{node_id}
+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.
 
-Updates a node.
+Nodes in the ``available`` state may have workloads provisioned on them; they are
+"available" for use.
 
+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.
 
-Normal response codes: 200
-Error response codes:413,415,405,404,403,401,400,503,409,
+Normal response codes: 201
 
+.. TODO: add error codes
 
 Request
 -------
 
 .. rest_parameters:: parameters.yaml
 
-   - node_id: node_id
-
-
+   - driver: r_driver_name
 
+**Example Node creation request:**
 
-Response Example
-----------------
-
-.. literalinclude:: samples/node-show-response.json
+.. literalinclude:: samples/node-create-request.json
    :language: javascript
 
+Response
+--------
+
+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.
 
+The list and example below are representative of the response as of API microversion 1.16.
 
+.. rest_parameters:: parameters.yaml
 
+    - uuid: node_uuid
+    - name: node_name
+    - power_state: power_state
+    - target_power_state: target_power_state
+    - provision_state: provision_state
+    - target_provision_state: target_provision_state
+    - maintenance: maintenance
+    - maintenance_reason: maintenance_reason
+    - last_error: last_error
+    - reservation: reservation
+    - driver: driver_name
+    - driver_info: driver_info
+    - driver_internal_info: driver_internal_info
+    - properties: n_properties
+    - instance_info: instance_info
+    - instance_uuid: instance_uuid
+    - chassis_uuid: chassis_uuid
+    - extra: extra
+    - console_enabled: console_enabled
+    - raid_config: raid_config
+    - target_raid_config: target_raid_config
+    - clean_step: clean_step
+    - links: links
+    - ports: n_ports
+    - states: n_states
+
+**Example JSON representation of a Node:**
+
+.. literalinclude:: samples/node-create-response.json
+   :language: javascript
 
 
+List Nodes
+==========
 
+.. rest_method::  GET /v1/nodes
 
+Return a list of bare metal Nodes, with some useful information about
+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.
 
-Delete 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.
 
-.. rest_method::  DELETE /v1/nodes/{node_id}
+API microversion 1.9 added the ``provision_state`` Request parameter, allowing
+the list of returned Nodes to be filtered by their current state.
 
-Deletes a node.
+API microversion 1.16 added the ``driver`` Request parameter, allowing
+the list of returned Nodes to be filtered by their driver name.
 
-Error response codes:204,413,415,405,404,403,401,400,503,409,
+Normal response codes: 200
 
+.. TODO: add error codes
 
 Request
 -------
 
 .. rest_parameters:: parameters.yaml
 
-   - node_id: node_id
-
-
-
-
-
-
-
-
+   - instance_uuid: r_instance_uuid
+   - maintenance: r_maintenance
+   - associated: r_associated
+   - provision_state: r_provision_state
+   - driver: r_driver
+   - fields: fields
+   - limit: limit
+   - marker: marker
+   - sort_dir: sort_dir
+   - sort_key: sort_key
 
+Response
+--------
 
+.. rest_parameters:: parameters.yaml
 
+    - uuid: uuid
+    - name: node_name
+    - instance_uuid: instance_uuid
+    - power_state: power_state
+    - provision_state: provision_state
+    - maintenance: maintenance
+    - links: links
 
+**Example list of Nodes:**
 
+.. literalinclude:: samples/nodes-list-response.json
+   :language: javascript
 
 
-List nodes with details
-=======================
+List Nodes Detailed
+===================
 
 .. rest_method::  GET /v1/nodes/detail
 
-Lists all nodes with details.
+Return a list of bare metal Nodes with complete details. Some filtering is
+possible by passing in flags with the request.
 
+This method is particularly useful to locate the Node associated to a given
+Nova instance, eg. with a request to ``v1/nodes/detail?instance_uuid={NOVA INSTANCE UUID}``
 
 Normal response codes: 200
-Error response codes:413,405,404,403,401,400,503,
 
+.. TODO: add error codes
 
 Request
 -------
 
+.. rest_parameters:: parameters.yaml
 
+   - instance_uuid: r_instance_uuid
+   - maintenance: r_maintenance
+   - associated: r_associated
+   - provision_state: r_provision_state
+   - driver: r_driver
+   - limit: limit
+   - marker: marker
+   - sort_dir: sort_dir
+   - sort_key: sort_key
 
+Response
+--------
 
+.. rest_parameters:: parameters.yaml
 
-Response Example
-----------------
+    - uuid: node_uuid
+    - name: node_name
+    - power_state: power_state
+    - target_power_state: target_power_state
+    - provision_state: provision_state
+    - target_provision_state: target_provision_state
+    - maintenance: maintenance
+    - maintenance_reason: maintenance_reason
+    - last_error: last_error
+    - reservation: reservation
+    - driver: driver_name
+    - driver_info: driver_info
+    - driver_internal_info: driver_internal_info
+    - properties: n_properties
+    - instance_info: instance_info
+    - instance_uuid: instance_uuid
+    - chassis_uuid: chassis_uuid
+    - extra: extra
+    - console_enabled: console_enabled
+    - raid_config: raid_config
+    - target_raid_config: target_raid_config
+    - clean_step: clean_step
+    - links: links
+    - ports: n_ports
+    - states: n_states
+
+**Example detailed list of Nodes:**
 
 .. literalinclude:: samples/nodes-list-details-response.json
    :language: javascript
 
 
+Show Node Details
+=================
 
+.. rest_method::  GET /v1/nodes/{node_ident}
 
+Shows details for a node. By default, this will return the full representation
+of the resource; an optional ``fields`` parameter can be supplied to return
+only the specified set.
 
+Normal response codes: 200
 
-
-
-
-
-
-Create node
-===========
-
-.. rest_method::  POST /v1/nodes
-
-Creates a node.
-
-Error response codes:201,413,415,405,404,403,401,400,503,409,
-
+.. TODO: add error codes
 
 Request
 -------
 
+.. rest_parameters:: parameters.yaml
 
+    - node_ident: node_ident
+    - fields: fields
 
+Response
+--------
 
+.. rest_parameters:: parameters.yaml
 
+    - uuid: node_uuid
+    - name: node_name
+    - power_state: power_state
+    - target_power_state: target_power_state
+    - provision_state: provision_state
+    - target_provision_state: target_provision_state
+    - maintenance: maintenance
+    - maintenance_reason: maintenance_reason
+    - last_error: last_error
+    - reservation: reservation
+    - driver: driver_name
+    - driver_info: driver_info
+    - driver_internal_info: driver_internal_info
+    - properties: n_properties
+    - instance_info: instance_info
+    - instance_uuid: instance_uuid
+    - chassis_uuid: chassis_uuid
+    - extra: extra
+    - console_enabled: console_enabled
+    - raid_config: raid_config
+    - target_raid_config: target_raid_config
+    - clean_step: clean_step
+    - links: links
+    - ports: n_ports
+    - states: n_states
+
+**Example JSON representation of a Node:**
 
+.. literalinclude:: samples/node-show-response.json
+   :language: javascript
 
 
+Update Node
+===========
 
+.. rest_method::  PATCH /v1/nodes/{node_ident}
 
+Updates the information stored about a Node.
 
-
-
-
-
-
-List nodes
-==========
-
-.. rest_method::  GET /v1/nodes
-
-Lists all nodes.
-
+Note that this endpoint can not be used to request state changes, which are
+managed through sub-resources.
 
 Normal response codes: 200
-Error response codes:413,405,404,403,401,400,503,
 
+.. TODO: add error codes
 
 Request
 -------
 
+The BODY of the PATCH request must be a JSON PATCH document, adhering to
+`RFC 6902 <https://tools.ietf.org/html/rfc6902>`_.
 
+.. rest_parameters:: parameters.yaml
 
+   - node_ident: node_ident
 
+**Example PATCH document updating Node driver_info:**
 
-Response Example
-----------------
+.. literalinclude:: samples/node-update-driver-info-request.json
 
-.. literalinclude:: samples/nodes-list-response.json
-   :language: javascript
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
 
+    - uuid: node_uuid
+    - name: node_name
+    - power_state: power_state
+    - target_power_state: target_power_state
+    - provision_state: provision_state
+    - target_provision_state: target_provision_state
+    - maintenance: maintenance
+    - maintenance_reason: maintenance_reason
+    - last_error: last_error
+    - reservation: reservation
+    - driver: driver_name
+    - driver_info: driver_info
+    - driver_internal_info: driver_internal_info
+    - properties: n_properties
+    - instance_info: instance_info
+    - instance_uuid: instance_uuid
+    - chassis_uuid: chassis_uuid
+    - extra: extra
+    - console_enabled: console_enabled
+    - raid_config: raid_config
+    - target_raid_config: target_raid_config
+    - clean_step: clean_step
+    - links: links
+    - ports: n_ports
+    - states: n_states
+
+**Example JSON representation of a Node:**
+
+.. literalinclude:: samples/node-update-driver-info-response.json
+   :language: javascript
 
 
+Delete Node
+===========
 
+.. rest_method::  DELETE /v1/nodes/{node_ident}
 
+Deletes a node.
 
+Normal response codes: 204
 
+.. TODO: add error codes
 
+Request
+-------
 
+.. rest_parameters:: parameters.yaml
 
+   - node_ident: node_ident
\ No newline at end of file
diff --git a/api-ref/source/baremetal-api-v1-ports.inc b/api-ref/source/baremetal-api-v1-ports.inc
index 73efb58d5..6846abf26 100644
--- a/api-ref/source/baremetal-api-v1-ports.inc
+++ b/api-ref/source/baremetal-api-v1-ports.inc
@@ -24,7 +24,7 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - port_id: port_id
+   - port_id: uuid
    - fields: fields
 
 
@@ -61,7 +61,7 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - port_id: port_id
+   - port_id: uuid
 
 
 
@@ -97,7 +97,7 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - port_id: port_id
+   - port_id: uuid
 
 
 
diff --git a/api-ref/source/baremetal-api-versions.inc b/api-ref/source/baremetal-api-versions.inc
new file mode 100644
index 000000000..4b74dd640
--- /dev/null
+++ b/api-ref/source/baremetal-api-versions.inc
@@ -0,0 +1,78 @@
+.. -*- rst -*-
+
+============
+API versions
+============
+
+Concepts
+========
+
+In order to bring new features to users over time, the Ironic API
+supports versioning. There are two kinds of versions in Ironic.
+
+- ''major versions'', which have dedicated urls.
+- ''microversions'', which can be requested through the use of the
+  ``X-OpenStack-Ironic-API-Version`` header.
+
+Beginning with the Kilo release, all API requests support the
+``X-OpenStack-Ironic-API-Version`` header. This header SHOULD be supplied
+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.
+
+List API versions
+=================
+
+.. rest_method::  GET /
+
+This fetches all the information about all known major API versions in the
+deployment. Links to more specific information will be provided for each major
+API version, as well as information about supported min and max microversions.
+
+Normal response codes: 200
+
+Request
+-------
+
+Response Example
+----------------
+
+.. rest_parameters::  parameters.yaml
+
+    - description: description
+    - versions: versions
+    - version: version
+    - id: id
+    - links: links
+    - min_version: x-openstack-ironic-api-min-version
+
+.. literalinclude:: samples/api-root-response.json
+   :language: javascript
+
+
+Show v1 API
+===========
+
+.. rest_method::  GET /v1/
+
+Show all the resources within the Ironic v1 API.
+
+Normal response codes: 200
+
+Request
+-------
+
+Response Example
+----------------
+
+.. rest_parameters::  parameters.yaml
+
+    - id: id
+    - links: links
+    - openstack-request-id: openstack-request-id
+    - x-openstack-ironic-api-version: header_version
+    - x-openstack-ironic-api-min-version: x-openstack-ironic-api-min-version
+    - x-openstack-ironic-api-max-version: x-openstack-ironic-api-max-version
+
+.. literalinclude:: samples/api-v1-root-response.json
+   :language: javascript
\ No newline at end of file
diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst
index da5a1cb38..dbe36f040 100644
--- a/api-ref/source/index.rst
+++ b/api-ref/source/index.rst
@@ -4,10 +4,21 @@
  Bare Metal API
 ================
 
+This documentation describes the REST API for the Ironic service, beginning with the
+5.1.0 (Mitaka) release.
+
+Version negotiation is implemented in the server. When the negotiated version
+is not the current maximum version, both request and response may not match what
+is presented in this document. Significant changes may be noted inline.
+
+
 .. rest_expand_all::
 
-.. include:: baremetal-api-v1-chassis.inc
-.. include:: baremetal-api-v1-drivers.inc
+.. include:: baremetal-api-versions.inc
 .. include:: baremetal-api-v1-nodes.inc
+.. include:: baremetal-api-v1-node-management.inc
+.. include:: baremetal-api-v1-node-passthru.inc
 .. include:: baremetal-api-v1-ports.inc
+.. include:: baremetal-api-v1-drivers.inc
+.. include:: baremetal-api-v1-chassis.inc
 
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 1ce2bbd19..c07174f2b 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -1,17 +1,54 @@
 # variables in header
-x-openstack-request-id:
+header_version:
+  description: |
+    Specific API microversion used to generate this response.
+  in: header
+  required: true
+  type: string
+openstack-request-id:
   description: >
-    foo
+    A unique ID for tracking the request. The request ID associated with the request
+    appears in the log lines for that request. By default, the middleware configuration
+    ensures that the request ID appears in the log files.
   in: header
   required: false
   type: string
+x-openstack-ironic-api-max-version:
+  description: |
+    Maximum API microversion supported by this endpoint, eg. "1.16"
+  in: header
+  required: true
+  type: string
+x-openstack-ironic-api-min-version:
+  description: |
+    Minimum API microversion supported by this endpoint, eg. "1.1"
+  in: header
+  required: true
+  type: string
+x-openstack-ironic-api-version:
+  description: >
+    A request SHOULD include this header to indicate to the Ironic API service what
+    version the client supports. The server will transform the response object into
+    compliance with the requested version, if it is supported, or return a
+    406 Not Supported error.
+    If this header is not supplied, the server will default to ``min_version``
+    in all responses.
+  in: header
+  required: true
+  type: string
 
 # variables in path
-driver_name:
+chassis_ident:
+  description: |
+    The UUID of the chassis.
+  in: path
+  required: true
+  type: string
+driver_ident:
   description: |
     The name of the driver.
   in: path
-  required: false
+  required: true
   type: string
 node_id:
   description: |
@@ -19,24 +56,31 @@ node_id:
   in: path
   required: false
   type: string
-port_id:
+node_ident:
+  description: |
+    The UUID or Name of the node.
+  in: path
+  required: true
+  type: string
+port_ident:
   description: |
     The UUID of the port.
   in: path
-  required: false
+  required: true
   type: string
 
-# variables in query
+
+# variables common to all query strings
 fields:
   description: |
-    One or more chassis fields to be returned in the response.
+    One or more fields to be returned in the response.
 
-    For example, the following request returns only the ``description``
-    field for each chassis:
+    For example, the following request returns only the ``uuid``
+    and ``name`` fields for each node:
 
     ::
 
-       GET /v1/chassis?fields=description
+       GET /v1/nodes?fields=uuid,name
   in: query
   required: false
   type: array
@@ -59,6 +103,51 @@ marker:
   in: query
   required: false
   type: string
+
+# variables in the vendor_passthru query string
+method_name:
+  description: |
+    Driver specific method name.
+  in: query
+  required: true
+  type: string
+
+# variables in the node query string
+r_associated:
+  description: |
+    Filter the list of returned nodes and only return which are, or are not,
+    associated with an ``instance_uuid``.
+  in: query
+  required: false
+  type: boolean
+r_driver:
+  description: |
+    Filter the list of returned nodes, and only return those with the specified
+    ``driver``.
+  in: query
+  required: false
+  type: string
+r_instance_uuid:
+  description: |
+    Filter the list of returned nodes, and only return the node with this
+    specific instance UUID, or an empty set if not found.
+  in: query
+  required: false
+  type: string
+r_maintenance:
+  description: |
+    Filter the list of returned nodes and only return those with
+    ``maintenance`` set to ``True`` or ``False``.
+  in: query
+  required: false
+  type: boolean
+r_provision_state:
+  description: |
+    Filter the list of returned nodes, and only return those with the specified
+    ``provision_state``.
+  in: query
+  required: false
+  type: string
 sort_dir:
   description: |
     Sorts the response by the requested sort
@@ -82,19 +171,55 @@ sort_key:
   required: false
   type: string
 
-# variables in body
+
+# variables in API response body
+boot_device:
+  description: |
+    The boot device for a Node, eg. "pxe" or "disk".
+  in: body
+  required: true
+  type: string
 chassis:
   description: |
     A ``chassis`` object.
   in: body
   required: true
   type: array
-chassis_1:
+chassis_uuid:
   description: |
-    A list of chassis objects.
+    UUID of the chassis associated with this Node. May be empty or None.
   in: body
   required: true
+  type: string
+clean_step:
+  description: |
+    The current clean step. Introduced with the cleaning feature.
+  in: body
+  required: false
+  type: string
+clean_steps:
+  description: |
+    An ordered list of cleaning steps that will be performed on the node. A
+    cleaning step is a dictionary with required keys ‘interface’ and ‘step’, and
+    optional key ‘args’. If specified, the value for ‘args’ is a keyword variable
+    argument dictionary that is passed to the cleaning step method.
+  in: body
+  required: false
   type: array
+configdrive:
+  description: |
+    A gzip'ed and base-64 encoded config drive, to be written to a partition
+    on the Node's boot disk. This parameter is only accepted when setting the
+    state to "active".
+  in: body
+  required: false
+  type: string or gzip+b64 blob
+console_enabled:
+  description: |
+    Indicates whether console access is enabled or disabled on this node.
+  in: body
+  required: true
+  type: boolean
 created_at:
   description: |
     The date and time when the resource was created.
@@ -115,13 +240,26 @@ created_at:
   type: string
 description:
   description: |
-    A description for the chassis.
+    Descriptive text about the Ironic service.
   in: body
-  required: false
+  required: true
   type: string
-description_1:
+driver_info:
+  description: |
+    All the metadata required by the driver to manage this Node. List of fields
+    varies between drivers, and can be retrieved from the ``/v1/drivers/<DRIVER_NAME>/properties`` resource.
+  in: body
+  required: true
+  type: JSON
+driver_internal_info:
   description: |
-    A description for the chassis.
+    Internal metadata set and stored by the Node's driver. This field is read-only.
+  in: body
+  required: false
+  type: JSON
+driver_name:
+  description: |
+    The name of the driver.
   in: body
   required: true
   type: string
@@ -134,43 +272,120 @@ drivers:
 extra:
   description: |
     A set of one or more arbitrary metadata key and
-    value pairs for the chassis.
+    value pairs.
   in: body
   required: false
   type: object
-extra_1:
-  description: |
-    A set of zero or more arbitrary metadata key and
-    value pairs for the chassis.
-  in: body
-  required: true
-  type: object
 hosts:
   description: |
     A list of active hosts that support this driver.
   in: body
   required: true
   type: array
-links:
+id:
   description: |
-    A list that contains a self link and associated
-    chassis links.
+    Major API version, eg, "v1"
   in: body
   required: true
-  type: array
-links_1:
+  type: string
+inspection_finished_at:
+  description: |
+    The date and time when the inspection process started.
+    May be "null"
+  in: body
+  required: true
+  type: string
+inspection_started_at:
+  description: |
+    The date and time when the inspection process started.
+    May be "null"
+  in: body
+  required: true
+  type: string
+instance_info:
+  description: |
+    Information used to customize the deployed image. May include root partition
+    size, a base 64 encoded config drive, and other metadata. Note that this field
+    is erased automatically when the instance is deleted (this is done by requesting
+    the Node provision state be changed to DELETED).
+  in: body
+  required: true
+  type: JSON
+instance_uuid:
+  description: |
+    UUID of the Nova instance associated with this Node.
+  in: body
+  required: true
+  type: string
+last_error:
+  description: |
+    Any error from the most recent (last) transaction that started but failed to finish.
+  in: body
+  required: true
+  type: string
+links:
   description: |
     A list of relative links. Includes the self and
     bookmark links.
   in: body
   required: true
   type: array
+maintenance:
+  description: |
+    Whether or not this Node is currently in "maintenance mode". Setting a Node
+    into maintenance mode removes it from the available resource pool and halts
+    some internal automation. This can happen manually (eg, via an API request)
+    or automatically when Ironic detects a hardware fault that prevents communication
+    with the machine.
+  in: body
+  required: true
+  type: boolean
+maintenance_reason:
+  description: |
+    User-settable description of the reason why this Node was placed into
+    maintenance mode
+  in: body
+  required: false
+  type: string
+n_ports:
+  description: |
+    Links to the collection of ports on this node
+  in: body
+  required: true
+  type: array
+n_properties:
+  description: |
+    Physical characteristics of this Node. Populated by ironic-inspector during
+    inspection. May be edited via the REST API at any time.
+  in: body
+  required: true
+  type: JSON
+n_states:
+  description: |
+    Links to the collection of states. Note that this resource is also used to
+    request state transitions.
+  in: body
+  required: true
+  type: array
 name:
   description: |
     The name of the driver.
   in: body
   required: true
   type: string
+node_name:
+  description: |
+    Human-readable identifier for the Node resource. May be undefined. Certain
+    words are reserved. Added in API microversion 1.5
+  in: body
+  required: false
+  type: string
+node_uuid:
+  description: |
+    UUID of the Node resource.
+  in: body
+  required: true
+  type: string
 nodes:
   description: |
     Links to the collection of nodes contained in
@@ -178,12 +393,103 @@ nodes:
   in: body
   required: true
   type: array
+persistent:
+  description: |
+    Whether the boot device should be set only for the next reboot, or
+    persistently.
+  in: body
+  required: true
+  type: boolean
+power_state:
+  description: |
+    The current power state of this Node. Usually, "power on" or "power off", but may be "None"
+    if Ironic is unable to determine the power state (eg, due to hardware failure).
+  in: body
+  required: true
+  type: string
 properties:
   description: |
     A list of links to driver properties.
   in: body
   required: true
   type: array
+provision_state:
+  description: |
+    The current provisioning state of this Node.
+  in: body
+  required: true
+  type: string
+provision_updated_at:
+  description: |
+    The date and time when the provision_state last changed.
+    ``null`` if the node is not being provisioned.
+  in: body
+  required: true
+  type: string
+r_driver_name:
+  description: |
+    The name of the driver used to manage this Node.
+  in: body
+  required: true
+  type: string
+raid_config:
+  description: |
+    Represents the current RAID configuration of the node. Introduced with
+    the cleaning feature.
+  in: body
+  required: false
+  type: JSON
+reason:
+  description: |
+    Specify the reason for setting the Node into maintenance mode.
+  in: body
+  required: false
+  type: string
+requested_provision_state:
+  description: |
+    One of the provisioning verbs: manage, provide, inspect, clean, active,
+    rebuild, delete (deleted), abort.
+  in: body
+  required: true
+  type: string
+reservation:
+  description: |
+    The ``name`` of an Ironic Conductor host which is holding a lock on this node,
+    if a lock is held. Usually "null", but this field can be useful for debugging.
+  in: body
+  required: true
+  type: string
+supported_boot_devices:
+  description: |
+    List of boot devices which this Node's driver supports.
+  in: body
+  required: true
+  type: array
+target_power_state:
+  description: |
+    If a power state transition has been requested, this field represents the
+    requested (ie, "target") state.
+  in: body
+  required: true
+  type: string
+target_provision_state:
+  description: |
+    If a provisioning action has been requested, this field represents the
+    requested (ie, "target") state. Note that a Node may go through several
+    states during its transition to this target state. For instance, when requesting
+    an instance be deployed to an AVAILABLE Node, the Node may go through the following
+    state change progression: AVAILABLE -> DEPLOYING -> DEPLOYWAIT -> DEPLOYING -> ACTIVE
+  in: body
+  required: true
+  type: string
+target_raid_config:
+  description: |
+    Represents the requested RAID configuration of the node, which will be
+    applied when the Node next transitions through the CLEANING state. Introduced
+    with the cleaning feature.
+  in: body
+  required: true
+  type: JSON
 updated_at:
   description: |
     The date and time when the resource was updated.
@@ -207,8 +513,64 @@ updated_at:
   type: string
 uuid:
   description: |
-    The UUID for the chassis.
+    The UUID for the resource.
   in: body
   required: true
   type: string
 
+# variables returned from node-validate
+v_boot:
+  description: |
+    Status of the "boot" interface
+  in: body
+  required: true
+  type: object
+v_console:
+  description: |
+    Status of the "console" interface
+  in: body
+  required: true
+  type: object
+v_deploy:
+  description: |
+    Status of the "deploy" interface
+  in: body
+  required: true
+  type: object
+v_inspect:
+  description: |
+    Status of the "inspect" interface
+  in: body
+  required: true
+  type: object
+v_management:
+  description: |
+    Status of the "management" interface
+  in: body
+  required: true
+  type: object
+v_power:
+  description: |
+    Status of the "power" interface
+  in: body
+  required: true
+  type: object
+v_raid:
+  description: |
+    Status of the "raid" interface
+  in: body
+  required: true
+  type: object
+
+version:
+  description: |
+    Versioning of this API response, eg. "1.16".
+  in: body
+  required: true
+  type: string
+versions:
+  description: |
+    Array of information about currently supported versions.
+  in: body
+  required: true
+  type: array
\ No newline at end of file
diff --git a/api-ref/source/samples/api-root-response.json b/api-ref/source/samples/api-root-response.json
new file mode 100644
index 000000000..3a860c34d
--- /dev/null
+++ b/api-ref/source/samples/api-root-response.json
@@ -0,0 +1,30 @@
+{
+   "name" : "OpenStack Ironic API",
+   "description" : "Ironic is an OpenStack project which aims to provision baremetal machines.",
+   "default_version" : {
+      "status" : "CURRENT",
+      "version" : "1.16",
+      "links" : [
+         {
+            "rel" : "self",
+            "href" : "http://127.0.0.1:6385/v1/"
+         }
+      ],
+      "id" : "v1",
+      "min_version" : "1.1"
+   },
+   "versions" : [
+      {
+         "status" : "CURRENT",
+         "links" : [
+            {
+               "href" : "http://127.0.0.1:6385/v1/",
+               "rel" : "self"
+            }
+         ],
+         "id" : "v1",
+         "version" : "1.16",
+         "min_version" : "1.1"
+      }
+   ]
+}
diff --git a/api-ref/source/samples/api-v1-root-response.json b/api-ref/source/samples/api-v1-root-response.json
new file mode 100644
index 000000000..9fcb56b91
--- /dev/null
+++ b/api-ref/source/samples/api-v1-root-response.json
@@ -0,0 +1,60 @@
+{
+   "chassis" : [
+      {
+         "rel" : "self",
+         "href" : "http://127.0.0.1:6385/v1/chassis/"
+      },
+      {
+         "href" : "http://127.0.0.1:6385/chassis/",
+         "rel" : "bookmark"
+      }
+   ],
+   "links" : [
+      {
+         "href" : "http://127.0.0.1:6385/v1/",
+         "rel" : "self"
+      },
+      {
+         "rel" : "describedby",
+         "type" : "text/html",
+         "href" : "http://docs.openstack.org/developer/ironic/dev/api-spec-v1.html"
+      }
+   ],
+   "nodes" : [
+      {
+         "rel" : "self",
+         "href" : "http://127.0.0.1:6385/v1/nodes/"
+      },
+      {
+         "rel" : "bookmark",
+         "href" : "http://127.0.0.1:6385/nodes/"
+      }
+   ],
+   "ports" : [
+      {
+         "href" : "http://127.0.0.1:6385/v1/ports/",
+         "rel" : "self"
+      },
+      {
+         "rel" : "bookmark",
+         "href" : "http://127.0.0.1:6385/ports/"
+      }
+   ],
+   "media_types" : [
+      {
+         "type" : "application/vnd.openstack.ironic.v1+json",
+         "base" : "application/json"
+      }
+   ],
+   "drivers" : [
+      {
+         "rel" : "self",
+         "href" : "http://127.0.0.1:6385/v1/drivers/"
+      },
+      {
+         "href" : "http://127.0.0.1:6385/drivers/",
+         "rel" : "bookmark"
+      }
+   ],
+   "id" : "v1"
+}
\ No newline at end of file
diff --git a/api-ref/source/samples/driver-get-response.json b/api-ref/source/samples/driver-get-response.json
index d1053fb87..5bc24e5b9 100644
--- a/api-ref/source/samples/driver-get-response.json
+++ b/api-ref/source/samples/driver-get-response.json
@@ -1,6 +1,30 @@
 {
-    "hosts": [
-        "fake-host"
-    ],
-    "name": "sample-driver"
-}
+    "drivers": [
+        {
+            "properties": [
+                {
+                    "href": "http://127.0.0.1:6385/v1/drivers/agent_ipmitool/properties",
+                    "rel": "self"
+                },
+                {
+                    "href": "http://127.0.0.1:6385/drivers/agent_ipmitool/properties",
+                    "rel": "bookmark"
+                }
+            ],
+            "hosts": [
+                "localhost"
+            ],
+            "name": "agent_ipmitool",
+            "links": [
+                {
+                    "rel": "self",
+                    "href": "http://127.0.0.1:6385/v1/drivers/agent_ipmitool"
+                },
+                {
+                    "rel": "bookmark",
+                    "href": "http://127.0.0.1:6385/drivers/agent_ipmitool"
+                }
+            ]
+        }
+    ]
+}
\ No newline at end of file
diff --git a/api-ref/source/samples/node-create-request.json b/api-ref/source/samples/node-create-request.json
new file mode 100644
index 000000000..d92220302
--- /dev/null
+++ b/api-ref/source/samples/node-create-request.json
@@ -0,0 +1,4 @@
+{
+    "driver": "agent_ipmitool",
+    "name": "test_node"
+}
diff --git a/api-ref/source/samples/node-create-response.json b/api-ref/source/samples/node-create-response.json
new file mode 100644
index 000000000..4e52c8f96
--- /dev/null
+++ b/api-ref/source/samples/node-create-response.json
@@ -0,0 +1,58 @@
+{
+   "last_error" : null,
+   "extra" : {},
+   "reservation" : null,
+   "driver" : "agent_ipmitool",
+   "instance_info" : {},
+   "created_at" : "2016-05-04T22:59:49.300836+00:00",
+   "raid_config" : {},
+   "uuid" : "14deb747-127c-4fe4-be9d-906c43006cd4",
+   "maintenance_reason" : null,
+   "target_provision_state" : null,
+   "ports" : [
+      {
+         "rel" : "self",
+         "href" : "http://127.0.0.1:6385/v1/nodes/14deb747-127c-4fe4-be9d-906c43006cd4/ports"
+      },
+      {
+         "rel" : "bookmark",
+         "href" : "http://127.0.0.1:6385/nodes/14deb747-127c-4fe4-be9d-906c43006cd4/ports"
+      }
+   ],
+   "power_state" : null,
+   "instance_uuid" : null,
+   "name" : "test_node_",
+   "properties" : {},
+   "clean_step" : {},
+   "console_enabled" : false,
+   "driver_internal_info" : {},
+   "target_power_state" : null,
+   "inspection_started_at" : null,
+   "provision_state" : "enroll",
+   "provision_updated_at" : null,
+   "driver_info" : {},
+   "inspection_finished_at" : null,
+   "updated_at" : null,
+   "links" : [
+      {
+         "rel" : "self",
+         "href" : "http://127.0.0.1:6385/v1/nodes/14deb747-127c-4fe4-be9d-906c43006cd4"
+      },
+      {
+         "href" : "http://127.0.0.1:6385/nodes/14deb747-127c-4fe4-be9d-906c43006cd4",
+         "rel" : "bookmark"
+      }
+   ],
+   "target_raid_config" : {},
+   "maintenance" : false,
+   "states" : [
+      {
+         "href" : "http://127.0.0.1:6385/v1/nodes/14deb747-127c-4fe4-be9d-906c43006cd4/states",
+         "rel" : "self"
+      },
+      {
+         "href" : "http://127.0.0.1:6385/nodes/14deb747-127c-4fe4-be9d-906c43006cd4/states",
+         "rel" : "bookmark"
+      }
+   ]
+}
diff --git a/api-ref/source/samples/node-get-or-set-boot-device.json b/api-ref/source/samples/node-get-or-set-boot-device.json
new file mode 100644
index 000000000..cb0141173
--- /dev/null
+++ b/api-ref/source/samples/node-get-or-set-boot-device.json
@@ -0,0 +1,4 @@
+{
+    "boot_device": "pxe",
+    "persistent": false
+}
diff --git a/api-ref/source/samples/node-get-state-response.json b/api-ref/source/samples/node-get-state-response.json
new file mode 100644
index 000000000..b33c8dfba
--- /dev/null
+++ b/api-ref/source/samples/node-get-state-response.json
@@ -0,0 +1,11 @@
+{
+   "last_error" : "",
+   "target_raid_config" : {},
+   "target_power_state" : null,
+   "console_enabled" : false,
+   "target_provision_state" : null,
+   "provision_updated_at" : null,
+   "power_state" : "power off",
+   "raid_config" : {},
+   "provision_state" : "available"
+}
diff --git a/api-ref/source/samples/node-get-supported-boot-devices-response.json b/api-ref/source/samples/node-get-supported-boot-devices-response.json
new file mode 100644
index 000000000..cf72fdfe8
--- /dev/null
+++ b/api-ref/source/samples/node-get-supported-boot-devices-response.json
@@ -0,0 +1,9 @@
+{
+   "supported_boot_devices" : [
+      "pxe",
+      "disk",
+      "cdrom",
+      "bios",
+      "safe"
+   ]
+}
diff --git a/api-ref/source/samples/node-maintenance-request.json b/api-ref/source/samples/node-maintenance-request.json
new file mode 100644
index 000000000..3cea207b5
--- /dev/null
+++ b/api-ref/source/samples/node-maintenance-request.json
@@ -0,0 +1,3 @@
+{
+    "reason": "Replacing the hard drive"
+}
\ No newline at end of file
diff --git a/api-ref/source/samples/node-set-active-state.json b/api-ref/source/samples/node-set-active-state.json
new file mode 100644
index 000000000..f89115ce4
--- /dev/null
+++ b/api-ref/source/samples/node-set-active-state.json
@@ -0,0 +1,4 @@
+{
+    "target": "active",
+    "configdrive": "http://127.0.0.1/images/test-node-config-drive.iso.gz"
+}
\ No newline at end of file
diff --git a/api-ref/source/samples/node-set-clean-state.json b/api-ref/source/samples/node-set-clean-state.json
new file mode 100644
index 000000000..0171a20f1
--- /dev/null
+++ b/api-ref/source/samples/node-set-clean-state.json
@@ -0,0 +1,12 @@
+{
+    "target": "clean",
+    "clean_steps": [
+        {
+            'interface': 'deploy',
+            'step': 'upgrade_firmware',
+            'args': {
+                'force': True
+            }
+        }
+    ]
+}
\ No newline at end of file
diff --git a/api-ref/source/samples/node-set-power-off.json b/api-ref/source/samples/node-set-power-off.json
new file mode 100644
index 000000000..5602f053d
--- /dev/null
+++ b/api-ref/source/samples/node-set-power-off.json
@@ -0,0 +1,3 @@
+{
+    "target": "power off"
+}
\ No newline at end of file
diff --git a/api-ref/source/samples/node-set-power-state.json b/api-ref/source/samples/node-set-power-state.json
new file mode 100644
index 000000000..11833351b
--- /dev/null
+++ b/api-ref/source/samples/node-set-power-state.json
@@ -0,0 +1,3 @@
+{
+    "target": "power on"
+}
\ No newline at end of file
diff --git a/api-ref/source/samples/node-set-raid-request.json b/api-ref/source/samples/node-set-raid-request.json
new file mode 100644
index 000000000..7bb7612d3
--- /dev/null
+++ b/api-ref/source/samples/node-set-raid-request.json
@@ -0,0 +1,9 @@
+{
+   "logical_disks" : [
+      {
+         "size_gb" : 100,
+         "is_root_volume" : true,
+         "raid_level" : "1"
+      }
+   ]
+}
diff --git a/api-ref/source/samples/node-show-response.json b/api-ref/source/samples/node-show-response.json
index 34cc5f7de..2e4bf1d02 100644
--- a/api-ref/source/samples/node-show-response.json
+++ b/api-ref/source/samples/node-show-response.json
@@ -1,63 +1,71 @@
 {
-    "chassis_uuid": "edcad704-b2da-41d5-96d9-afd580ecfa12",
-    "clean_step": {},
-    "console_enabled": false,
-    "created_at": "2000-01-01T12:00:00",
-    "driver": "fake",
-    "driver_info": {},
-    "driver_internal_info": {},
-    "extra": {},
-    "inspection_finished_at": null,
-    "inspection_started_at": "2000-01-01T12:00:00",
-    "instance_info": {},
-    "instance_uuid": "dcf1fbc5-93fc-4596-9395-b80572f6267b",
-    "last_error": null,
-    "links": [
-        {
-            "href": "http://localhost:6385/v1/nodes/1be26c0b-03f2-4d2e-ae87-c02d7f33c123",
-            "rel": "self"
-        },
-        {
-            "href": "http://localhost:6385/nodes/1be26c0b-03f2-4d2e-ae87-c02d7f33c123",
-            "rel": "bookmark"
-        }
-    ],
-    "maintenance": false,
-    "maintenance_reason": null,
-    "name": "database16-dc02",
-    "ports": [
-        {
-            "href": "http://localhost:6385/v1/nodes/1be26c0b-03f2-4d2e-ae87-c02d7f33c123/ports",
-            "rel": "self"
-        },
-        {
-            "href": "http://localhost:6385/nodes/1be26c0b-03f2-4d2e-ae87-c02d7f33c123/ports",
-            "rel": "bookmark"
-        }
-    ],
-    "power_state": "power on",
-    "properties": {
-        "cpus": "1",
-        "local_gb": "10",
-        "memory_mb": "1024"
-    },
-    "provision_state": "active",
-    "provision_updated_at": "2000-01-01T12:00:00",
-    "raid_config": null,
-    "reservation": null,
-    "states": [
-        {
-            "href": "http://localhost:6385/v1/nodes/1be26c0b-03f2-4d2e-ae87-c02d7f33c123/states",
-            "rel": "self"
-        },
-        {
-            "href": "http://localhost:6385/nodes/1be26c0b-03f2-4d2e-ae87-c02d7f33c123/states",
-            "rel": "bookmark"
-        }
-    ],
-    "target_power_state": null,
-    "target_provision_state": null,
-    "target_raid_config": null,
-    "updated_at": "2000-01-01T12:00:00",
-    "uuid": "1be26c0b-03f2-4d2e-ae87-c02d7f33c123"
+   "target_provision_state" : null,
+   "instance_info" : {},
+   "updated_at" : "2016-05-05T00:28:40+00:00",
+   "maintenance_reason" : null,
+   "inspection_started_at" : null,
+   "target_power_state" : null,
+   "ports" : [
+      {
+         "rel" : "self",
+         "href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/ports"
+      },
+      {
+         "href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/ports",
+         "rel" : "bookmark"
+      }
+   ],
+   "maintenance" : false,
+   "driver" : "fake",
+   "provision_state" : "available",
+   "reservation" : null,
+   "uuid" : "ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb",
+   "extra" : {
+      "foo" : "bar"
+   },
+   "driver_internal_info" : {},
+   "states" : [
+      {
+         "href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/states",
+         "rel" : "self"
+      },
+      {
+         "rel" : "bookmark",
+         "href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/states"
+      }
+   ],
+   "target_raid_config" : {},
+   "console_enabled" : false,
+   "clean_step" : {},
+   "last_error" : null,
+   "links" : [
+      {
+         "rel" : "self",
+         "href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb"
+      },
+      {
+         "rel" : "bookmark",
+         "href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb"
+      }
+   ],
+   "provision_updated_at" : null,
+   "name" : "test_node",
+   "properties" : {
+      "local_gb" : 10,
+      "cpu_arch" : "x86_64",
+      "cpus" : 1,
+      "memory_mb" : 1024
+   },
+   "power_state" : "power off",
+   "created_at" : "2016-04-20T16:51:03+00:00",
+   "instance_uuid" : null,
+   "raid_config" : {},
+   "driver_info" : {
+      "ipmi_password" : "***",
+      "ipmi_username" : "ADMIN",
+      "ipmi_address" : "1.2.3.4",
+      "deploy_kernel" : "http://127.0.0.1/images/kernel",
+      "deploy_ramdisk" : "http://127.0.0.1/images/ramdisk"
+   },
+   "inspection_finished_at" : null
 }
diff --git a/api-ref/source/samples/node-update-driver-info-request.json b/api-ref/source/samples/node-update-driver-info-request.json
new file mode 100644
index 000000000..7c4fe53ba
--- /dev/null
+++ b/api-ref/source/samples/node-update-driver-info-request.json
@@ -0,0 +1,12 @@
+[
+   {
+      "op" : "replace",
+      "path" : "/driver_info/ipmi_username",
+      "value" : "OPERATOR"
+   },
+   {
+      "value" : "10.0.0.123",
+      "op" : "replace",
+      "path" : "/driver_info/ipmi_address"
+   }
+]
diff --git a/api-ref/source/samples/node-update-driver-info-response.json b/api-ref/source/samples/node-update-driver-info-response.json
new file mode 100644
index 000000000..6f9a6cf2f
--- /dev/null
+++ b/api-ref/source/samples/node-update-driver-info-response.json
@@ -0,0 +1,71 @@
+{
+   "properties" : {
+      "memory_mb" : 1024,
+      "cpus" : 1,
+      "local_gb" : 10,
+      "cpu_arch" : "x86_64"
+   },
+   "maintenance_reason" : null,
+   "instance_info" : {},
+   "states" : [
+      {
+         "rel" : "self",
+         "href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/states"
+      },
+      {
+         "href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/states",
+         "rel" : "bookmark"
+      }
+   ],
+   "driver_internal_info" : {},
+   "power_state" : "power off",
+   "console_enabled" : false,
+   "last_error" : null,
+   "target_raid_config" : {},
+   "maintenance" : false,
+   "provision_state" : "available",
+   "uuid" : "ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb",
+   "links" : [
+      {
+         "rel" : "self",
+         "href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb"
+      },
+      {
+         "href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb",
+         "rel" : "bookmark"
+      }
+   ],
+   "clean_step" : {},
+   "created_at" : "2016-04-20T16:51:03+00:00",
+   "instance_uuid" : null,
+   "target_power_state" : null,
+   "driver_info" : {
+      "ipmi_address" : "10.0.0.123",
+      "deploy_ramdisk" : "http://127.0.0.1/images/ramdisk",
+      "deploy_kernel" : "http://127.0.0.1/images/kernel",
+      "ipmi_password" : "***",
+      "ipmi_username" : "OPERATOR"
+   },
+   "inspection_started_at" : null,
+   "raid_config" : {},
+   "inspection_finished_at" : null,
+   "reservation" : null,
+   "target_provision_state" : null,
+   "extra" : {
+      "foo" : "bar"
+   },
+   "driver" : "fake",
+   "name" : "test_node",
+   "updated_at" : "2016-05-05T18:43:41+00:00",
+   "ports" : [
+      {
+         "href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/ports",
+         "rel" : "self"
+      },
+      {
+         "rel" : "bookmark",
+         "href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/ports"
+      }
+   ],
+   "provision_updated_at" : null
+}
diff --git a/api-ref/source/samples/node-validate-response.json b/api-ref/source/samples/node-validate-response.json
new file mode 100644
index 000000000..8f466845c
--- /dev/null
+++ b/api-ref/source/samples/node-validate-response.json
@@ -0,0 +1,27 @@
+{
+   "management" : {
+      "result" : true
+   },
+   "inspect" : {
+      "result" : null,
+      "reason" : "not supported"
+   },
+   "power" : {
+      "result" : true
+   },
+   "raid" : {
+      "result" : true
+   },
+   "boot" : {
+      "result" : false,
+      "reason" : "Cannot validate image information for node ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb because one or more parameters are missing from its instance_info.. Missing are: ['ramdisk', 'kernel', 'image_source']"
+   },
+   "console" : {
+      "result" : false,
+      "reason" : "Missing 'ipmi_terminal_port' parameter in node's driver_info."
+   },
+   "deploy" : {
+      "reason" : "Cannot validate image information for node ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb because one or more parameters are missing from its instance_info.. Missing are: ['ramdisk', 'kernel', 'image_source']",
+      "result" : false
+   }
+}
diff --git a/api-ref/source/samples/node-vendor-passthru-response.json b/api-ref/source/samples/node-vendor-passthru-response.json
new file mode 100644
index 000000000..28fb22c4c
--- /dev/null
+++ b/api-ref/source/samples/node-vendor-passthru-response.json
@@ -0,0 +1,26 @@
+{
+   "bmc_reset" : {
+      "async" : true,
+      "description" : "",
+      "http_methods" : [
+         "POST"
+      ],
+      "attach" : false
+   },
+   "send_raw" : {
+      "description" : "",
+      "attach" : false,
+      "http_methods" : [
+         "POST"
+      ],
+      "async" : true
+   },
+   "heartbeat" : {
+      "async" : true,
+      "attach" : false,
+      "http_methods" : [
+         "POST"
+      ],
+      "description" : ""
+   }
+}
diff --git a/api-ref/source/samples/nodes-list-details-response.json b/api-ref/source/samples/nodes-list-details-response.json
index 17487fd3c..3a26d2bd6 100644
--- a/api-ref/source/samples/nodes-list-details-response.json
+++ b/api-ref/source/samples/nodes-list-details-response.json
@@ -1,64 +1,75 @@
 {
-    "nodes": [
-        {
-            "chassis_uuid": "633f9f21-5bd5-4166-b811-1eb01490c4ab",
-            "clean_step": {},
-            "console_enabled": false,
-            "created_at": "2016-04-23T10:52:43+00:00",
-            "driver": "pxe_ssh",
-            "driver_info": {
-                "deploy_kernel": "aadebece-ce44-4cf6-a9e8-545f0e8ac9f3",
-                "deploy_ramdisk": "cfe6f9ce-b2e6-4a7a-9246-0cc7eeb89a71",
-                "ssh_address": "localhost",
-                "ssh_key_filename": "/opt/stack/data/ironic/ssh_keys/ironic_key",
-                "ssh_port": 22,
-                "ssh_username": "ubuntu",
-                "ssh_virt_type": "virsh"
+   "nodes" : [
+      {
+         "reservation" : null,
+         "driver" : "agent_ipmitool",
+         "uuid" : "ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb",
+         "extra" : {
+            "foo" : "bar"
+         },
+         "provision_updated_at" : null,
+         "provision_state" : "available",
+         "clean_step" : {},
+         "maintenance" : false,
+         "driver_internal_info" : {},
+         "console_enabled" : false,
+         "raid_config" : {},
+         "target_raid_config" : {},
+         "inspection_started_at" : null,
+         "instance_info" : {},
+         "states" : [
+            {
+               "rel" : "self",
+               "href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/states"
             },
-            "driver_internal_info": {},
-            "extra": {},
-            "inspection_finished_at": null,
-            "inspection_started_at": null,
-            "instance_info": {},
-            "instance_uuid": null,
-            "last_error": null,
-            "links": [
-                {
-                    "href": "http://localhost:6385/v1/nodes/277c9fe9-a385-4e45-9399-660f3287e48c",
-                    "rel": "self"
-                },
-                {
-                    "href": "http://localhost:6385/nodes/277c9fe9-a385-4e45-9399-660f3287e48c",
-                    "rel": "bookmark"
-                }
-            ],
-            "maintenance": false,
-            "maintenance_reason": null,
-            "name": "node-0",
-            "ports": [
-                {
-                    "href": "http://localhost:6385/v1/nodes/277c9fe9-a385-4e45-9399-660f3287e48c/ports",
-                    "rel": "self"
-                },
-                {
-                    "href": "http://localhost:6385/nodes/277c9fe9-a385-4e45-9399-660f3287e48c/ports",
-                    "rel": "bookmark"
-                }
-            ],
-            "power_state": "power off",
-            "properties": {
-                "cpu_arch": "x86_64",
-                "cpus": 1,
-                "local_gb": 10,
-                "memory_mb": 1024
+            {
+               "href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/states",
+               "rel" : "bookmark"
+            }
+         ],
+         "last_error" : null,
+         "properties" : {
+            "cpus" : 1,
+            "memory_mb" : 1024,
+            "local_gb" : 10,
+            "cpu_arch" : "x86_64"
+         },
+         "links" : [
+            {
+               "rel" : "self",
+               "href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb"
             },
-            "provision_state": "available",
-            "provision_updated_at": null,
-            "reservation": null,
-            "target_power_state": null,
-            "target_provision_state": null,
-            "updated_at": "2016-04-23T10:53:37+00:00",
-            "uuid": "277c9fe9-a385-4e45-9399-660f3287e48c"
-        }
-    ]
+            {
+               "rel" : "bookmark",
+               "href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb"
+            }
+         ],
+         "name" : "test_node",
+         "ports" : [
+            {
+               "rel" : "self",
+               "href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/ports"
+            },
+            {
+               "rel" : "bookmark",
+               "href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/ports"
+            }
+         ],
+         "created_at" : "2016-04-20T16:51:03+00:00",
+         "updated_at" : "2016-05-04T23:24:20+00:00",
+         "maintenance_reason" : null,
+         "inspection_finished_at" : null,
+         "driver_info" : {
+            "deploy_kernel" : "http://127.0.0.1/images/kernel",
+            "ipmi_address" : "1.2.3.4",
+            "deploy_ramdisk" : "http://127.0.0.1/images/ramdisk",
+            "ipmi_password" : "******",
+            "ipmi_username" : "ADMIN",
+         },
+         "instance_uuid" : null,
+         "power_state" : "power off",
+         "target_power_state" : null,
+         "target_provision_state" : null
+      }
+   ]
 }
diff --git a/api-ref/source/samples/nodes-list-response.json b/api-ref/source/samples/nodes-list-response.json
index 8acb80205..a516ed54f 100644
--- a/api-ref/source/samples/nodes-list-response.json
+++ b/api-ref/source/samples/nodes-list-response.json
@@ -1,22 +1,22 @@
 {
-    "nodes": [
-        {
-            "instance_uuid": "dcf1fbc5-93fc-4596-9395-b80572f6267b",
-            "links": [
-                {
-                    "href": "http://localhost:6385/v1/nodes/1be26c0b-03f2-4d2e-ae87-c02d7f33c123",
-                    "rel": "self"
-                },
-                {
-                    "href": "http://localhost:6385/nodes/1be26c0b-03f2-4d2e-ae87-c02d7f33c123",
-                    "rel": "bookmark"
-                }
-            ],
-            "maintenance": false,
-            "name": "database16-dc02",
-            "power_state": "power on",
-            "provision_state": "active",
-            "uuid": "1be26c0b-03f2-4d2e-ae87-c02d7f33c123"
-        }
-    ]
+   "nodes" : [
+      {
+         "provision_state" : "available",
+         "name" : "test_node",
+         "maintenance" : false,
+         "uuid" : "ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb",
+         "links" : [
+            {
+               "href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb",
+               "rel" : "self"
+            },
+            {
+               "href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb",
+               "rel" : "bookmark"
+            }
+         ],
+         "instance_uuid" : null,
+         "power_state" : "power off"
+      }
+   ]
 }