From 172512a64ad67cbfb41cc88ba7a8eebf76543ca1 Mon Sep 17 00:00:00 2001 From: Dmitry Tantsur Date: Wed, 29 Jul 2015 13:36:00 +0200 Subject: [PATCH] Document API versioning This change moves documentation of API versioning from inline comments to our docs. Change-Id: Iaac7e1178f605956bed5b31998ba4599a1be0750 --- doc/source/deploy/install-guide.rst | 2 + doc/source/webapi/v1.rst | 131 ++++++++++++++++++++++++++ ironic/api/controllers/v1/__init__.py | 36 ++++--- 3 files changed, 150 insertions(+), 19 deletions(-) diff --git a/doc/source/deploy/install-guide.rst b/doc/source/deploy/install-guide.rst index 8dec80b506..c5928d6896 100644 --- a/doc/source/deploy/install-guide.rst +++ b/doc/source/deploy/install-guide.rst @@ -1449,6 +1449,8 @@ UUID interchangeably. .. _wiki_hostname: http://en.wikipedia.org/wiki/Hostname +.. _inspection: + Hardware Inspection ------------------- diff --git a/doc/source/webapi/v1.rst b/doc/source/webapi/v1.rst index c07dfc7e0c..96302032d9 100644 --- a/doc/source/webapi/v1.rst +++ b/doc/source/webapi/v1.rst @@ -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 ======= diff --git a/ironic/api/controllers/v1/__init__.py b/ironic/api/controllers/v1/__init__.py index 7139f0275a..d68d6609e5 100644 --- a/ironic/api/controllers/v1/__init__.py +++ b/ironic/api/controllers/v1/__init__.py @@ -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'