Document API versioning

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

Change-Id: Iaac7e1178f605956bed5b31998ba4599a1be0750

1 files changed, 131 insertions, 0 deletions

diff --git a/doc/source/webapi/v1.rst b/doc/source/webapi/v1.rst
index c07dfc7e0..96302032d 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
 =======