===================== 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: