172512a64a
This change moves documentation of API versioning from inline comments to our docs. Change-Id: Iaac7e1178f605956bed5b31998ba4599a1be0750
217 lines
6.6 KiB
ReStructuredText
217 lines
6.6 KiB
ReStructuredText
=====================
|
|
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.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 ran, to verify basic hardware control.
|
|
On success the node moves to ``manageable`` provision state, then the
|
|
``provide`` action must be run, which will clean the node and
|
|
make it 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 ``managable`` 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: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:
|