ironic/doc/source/webapi/v1.rst

====================
RESTful Web API (v1)
====================

API Versioning
==============

Starting with the Kilo release ironic supports versioning of API. Version is
defined as a string of 2 integers separated by a dot: **X.Y**. Here ``X`` is a
major version, always equal to ``1`` at the moment of writing, ``Y`` is
a minor version. Server minor version is increased every time the API behavior
is changed (note `Exceptions from Versioning`_). `Nova versioning
documentation`_ has a nice guide on when to bump an API version.

Server indicates its minimum and maximum supported API versions in the
``X-OpenStack-Ironic-API-Minimum-Version`` and
``X-OpenStack-Ironic-API-Maximum-Version`` headers respectively, returned
with every response. Client may request a specific API version by providing
``X-OpenStack-Ironic-API-Version`` header with request.

If no version is requested by the client, minimum supported version - **1.1**,
is assumed. The client is only exposed to those API features that are supported
in the requested (explicitly or implicitly) API version (again note `Exceptions
from Versioning`_, they are not covered by this rule).

We recommend clients requiring stable API to always request a specific version
of API. However, a special value ``latest`` can be requested instead, which
always requests the newest supported API version.

.. _Nova versioning documentation: http://docs.openstack.org/developer/nova/api_microversion_dev.html#when-do-i-need-a-new-microversion

API Versions History
--------------------

**1.18**

    Add ``internal_info`` readonly field to the port object, that will be used
    by ironic to store internal port-related information.

**1.17**

    Addition of provision_state verb ``adopt`` which allows an operator
    to move a node from ``manageable`` state to ``active`` state without
    performing a deployment operation on the node. This is intended for
    nodes that have already been deployed by external means.

**1.16**

    Add ability to filter nodes by driver.

**1.15**

    Add ability to do manual cleaning when a node is in the manageable
    provision state via PUT v1/nodes/<identifier>/states/provision,
    target:clean, clean_steps:[...].

**1.14**

    Make the following endpoints discoverable via Ironic API:
    * '/v1/nodes/<UUID or logical name>/states'
    * '/v1/drivers/<driver name>/properties'

**1.13**

    Add a new verb ``abort`` to the API used to abort nodes in
    ``CLEANWAIT`` state.

**1.12**

    This API version adds the following abilities:

    * Get/set ``node.target_raid_config`` and to get
      ``node.raid_config``.
    * Retrieve the logical disk properties for the driver.

**1.11** (breaking change)

    Newly registered nodes begin in the ``enroll`` provision state by default,
    instead of ``available``. To get them to the ``available`` state,
    the ``manage`` action must first be run to verify basic hardware control.
    On success the node moves to ``manageable`` provision state. Then the
    ``provide`` action must be run. Automated cleaning of the node is done and
    the node is made ``available``.

**1.10**

    Logical node names support all RFC 3986 unreserved characters.
    Previously only valid fully qualified domain names could be used.

**1.9**

    Add ability to filter nodes by provision state.

**1.8**

    Add ability to return a subset of resource fields.

**1.7**

    Add node ``clean_step`` field.

**1.6**

    Add :ref:`inspection` process: introduce ``inspecting`` and ``inspectfail``
    provision states, and ``inspect`` action that can be used when a node is in
    ``manageable`` provision state.

**1.5**

    Add logical node names that can be used to address a node in addition to
    the node UUID. Name is expected to be a valid `fully qualified domain
    name`_ in this version of API.

**1.4**

    Add ``manageable`` state and ``manage`` transition, which can be used to
    move a node to ``manageable`` state from ``available``.
    The node cannot be deployed in ``manageable`` state.
    This change is mostly a preparation for future inspection work
    and introduction of ``enroll`` provision state.

**1.3**

    Add node ``driver_internal_info`` field.

**1.2** (breaking change)

    Renamed NOSTATE (``None`` in Python, ``null`` in JSON) node state to
    ``available``. This is needed to reduce confusion around ``None`` state,
    especially when future additions to the state machine land.

**1.1**

    This was the initial version when API versioning was introduced.
    Includes the following changes from Kilo release cycle:

    * Add node ``maintenance_reason`` field and an API endpoint to
      set/unset the node maintenance mode.

    * Add sync and async support for vendor passthru methods.

    * Vendor passthru endpoints support different HTTP methods, not only
      ``POST``.

    * Make vendor methods discoverable via the Ironic API.

    * Add logic to store the config drive passed by Nova.

    This has been the minimum supported version since versioning was
    introduced.

**1.0**

    This version denotes Juno API and was never explicitly supported, as API
    versioning was not implemented in Juno, and **1.1** became the minimum
    supported version in Kilo.

.. _fully qualified domain name: https://en.wikipedia.org/wiki/Fully_qualified_domain_name

Exceptions from Versioning
--------------------------

The following API-visible things are not covered by the API versioning:

* Current node state is always exposed as it is, even if not supported by the
  requested API version, with exception of ``available`` state, which is
  returned in version 1.1 as ``None`` (in Python) or ``null`` (in JSON).

* Data within free-form JSON attributes: ``properties``, ``driver_info``,
  ``instance_info``, ``driver_internal_info`` fields on a node object;
  ``extra`` fields on all objects.

* Addition of new drivers.

* All vendor passthru methods.

Chassis
=======

.. rest-controller:: ironic.api.controllers.v1.chassis:ChassisController
   :webprefix: /v1/chassis

.. autotype:: ironic.api.controllers.v1.chassis.ChassisCollection
   :members:

.. autotype:: ironic.api.controllers.v1.chassis.Chassis
   :members:


Drivers
=======

.. rest-controller:: ironic.api.controllers.v1.driver:DriversController
   :webprefix: /v1/drivers

.. rest-controller:: ironic.api.controllers.v1.driver:DriverRaidController
   :webprefix: /v1/drivers/(driver_name)/raid

.. rest-controller:: ironic.api.controllers.v1.driver:DriverPassthruController
   :webprefix: /v1/drivers/(driver_name)/vendor_passthru

.. autotype:: ironic.api.controllers.v1.driver.DriverList
   :members:

.. autotype:: ironic.api.controllers.v1.driver.Driver
   :members:


Links
=====

.. autotype:: ironic.api.controllers.link.Link
   :members:


Nodes
=====

.. rest-controller:: ironic.api.controllers.v1.node:NodesController
   :webprefix: /v1/nodes

.. rest-controller:: ironic.api.controllers.v1.node:NodeMaintenanceController
   :webprefix: /v1/nodes/(node_ident)/maintenance

.. rest-controller:: ironic.api.controllers.v1.node:BootDeviceController
   :webprefix: /v1/nodes/(node_ident)/management/boot_device

.. rest-controller:: ironic.api.controllers.v1.node:NodeStatesController
   :webprefix: /v1/nodes/(node_ident)/states

.. rest-controller:: ironic.api.controllers.v1.node:NodeConsoleController
   :webprefix: /v1/nodes/(node_ident)/states/console

.. rest-controller:: ironic.api.controllers.v1.node:NodeVendorPassthruController
   :webprefix: /v1/nodes/(node_ident)/vendor_passthru

.. autotype:: ironic.api.controllers.v1.node.ConsoleInfo
   :members:

.. autotype:: ironic.api.controllers.v1.node.Node
   :members:

.. autotype:: ironic.api.controllers.v1.node.NodeCollection
   :members:

.. autotype:: ironic.api.controllers.v1.node.NodeStates
   :members:


Ports
=====

.. rest-controller:: ironic.api.controllers.v1.port:PortsController
   :webprefix: /v1/ports

.. autotype:: ironic.api.controllers.v1.port.PortCollection
   :members:

.. autotype:: ironic.api.controllers.v1.port.Port
   :members: