openstack/ironic
Code Issues Proposed changes

Document API versioning

Browse Source 
This change moves documentation of API versioning from inline
comments to our docs.

Change-Id: Iaac7e1178f605956bed5b31998ba4599a1be0750
This commit is contained in:
Dmitry Tantsur 2015-07-29 13:36:00 +02:00
parent d4aa1428ae
commit 172512a64a
3 changed files with 150 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/source/deploy/install-guide.rst
View File

@ -1449,6 +1449,8 @@ UUID interchangeably.
.. _wiki_hostname: http://en.wikipedia.org/wiki/Hostname
.. _inspection:
Hardware Inspection
-------------------

131
doc/source/webapi/v1.rst
View File

@ -2,6 +2,137 @@
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
=======

36
ironic/api/controllers/v1/__init__.py
View File

@ -38,25 +38,21 @@ from ironic.common.i18n import _
BASE_VERSION = 1
# NOTE(deva): v1.0 is reserved to indicate Juno's API, but is not presently
# supported by the API service. All changes between Juno and the
# point where we added microversioning are considered backwards-
# compatible, but are not specifically discoverable at this time.
# Here goes a short log of changes in every version.
# Refer to doc/source/webapi/v1.rst for a detailed explanation of what
# each version contains, and don't forget to update it when introducing
# a new version.
#
# The v1.1 version indicates this "initial" version as being
# different from Juno (v1.0), and includes the following changes:
#
# 827db7fe: Add Node.maintenance_reason
# 68eed82b: Add API endpoint to set/unset the node maintenance mode
# bc973889: Add sync and async support for passthru methods
# e03f443b: Vendor endpoints to support different HTTP methods
# e69e5309: Make vendor methods discoverable via the Ironic API
# edf532db: Add logic to store the config drive passed by Nova
# v1.1: API at the point in time when microversioning support was added
MIN_VER_STR = '1.1'
# v1.2: Renamed NOSTATE ("None") to AVAILABLE ("available") [breaking change]
# v1.0: corresponds to Juno API, not supported since Kilo
# v1.1: API at the point in time when versioning support was added,
# covers the following commits from Kilo cycle:
# 827db7fe: Add Node.maintenance_reason
# 68eed82b: Add API endpoint to set/unset the node maintenance mode
# bc973889: Add sync and async support for passthru methods
# e03f443b: Vendor endpoints to support different HTTP methods
# e69e5309: Make vendor methods discoverable via the Ironic API
# edf532db: Add logic to store the config drive passed by Nova
# v1.2: Renamed NOSTATE ("None") to AVAILABLE ("available")
# v1.3: Add node.driver_internal_info
# v1.4: Add MANAGEABLE state
# v1.5: Add logical node names
@ -65,7 +61,9 @@ MIN_VER_STR = '1.1'
# v1.8: Add ability to return a subset of resource fields
# v1.9: Add ability to filter nodes by provision state
# v1.10: Logical node names support RFC 3986 unreserved characters
# v1.11: Nodes appear in ENROLL state by default [breaking change]
# v1.11: Nodes appear in ENROLL state by default
MIN_VER_STR = '1.1'
MAX_VER_STR = '1.11'