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

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

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

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
+# Here goes a short log of changes in every version.
-#             supported by the API service. All changes between Juno and the
+# Refer to doc/source/webapi/v1.rst for a detailed explanation of what
-#             point where we added microversioning are considered backwards-
+# each version contains, and don't forget to update it when introducing
-#             compatible, but are not specifically discoverable at this time.
+# a new version.
-#
-#             The v1.1 version indicates this "initial" version as being
-#             different from Juno (v1.0), and includes the following changes:
 #
+# 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.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.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'