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.

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 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.

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

ironic.api.controllers.v1.chassis:ChassisController

ironic.api.controllers.v1.chassis.ChassisCollection

ironic.api.controllers.v1.chassis.Chassis

Drivers

ironic.api.controllers.v1.driver:DriversController

ironic.api.controllers.v1.driver:DriverPassthruController

ironic.api.controllers.v1.driver.DriverList

ironic.api.controllers.v1.driver.Driver

Links

ironic.api.controllers.link.Link

Nodes

ironic.api.controllers.v1.node:NodesController

ironic.api.controllers.v1.node:NodeMaintenanceController

ironic.api.controllers.v1.node:BootDeviceController

ironic.api.controllers.v1.node:NodeStatesController

ironic.api.controllers.v1.node:NodeConsoleController

ironic.api.controllers.v1.node:NodeVendorPassthruController

ironic.api.controllers.v1.node.ConsoleInfo

ironic.api.controllers.v1.node.Node

ironic.api.controllers.v1.node.NodeCollection

ironic.api.controllers.v1.node.NodeStates

Ports

ironic.api.controllers.v1.port:PortsController

ironic.api.controllers.v1.port.PortCollection

ironic.api.controllers.v1.port.Port