Add version discover guideline for API microversions

This guidelines describes how the client can request the
available microversions from the server.

Change-Id: I96a5084e5c44f030c19ed31f123b90cd184174b7

guidelines/errors.rst

@@ -1,3 +1,5 @@
+.. _errors:
+
 Errors
 ======
 

guidelines/microversion-errors-example.json

@@ -0,0 +1,19 @@
+ {
+    "errors": [
+        {
+            "request_id": "2ee92f06-8ede-4fb4-8921-b507601fb59d",
+            "code": "compute.microverion-unsupported",
+            "status": 406,
+            "title": "Requested microversion is unsupported",
+            "detail": "Version 5.3 is not supported by the API. Minimum is 2.1 and maximum is 5.2.",
+            "max_version": "5.2",
+            "min_version": "2.1",
+            "links": [
+                {
+                    "rel": "help",
+                    "href": "http://developer.openstack.org/api-guide/compute/microversions.html"
+                }
+             ]
+         }
+     ]
+}

guidelines/microversion_specification.rst

@@ -23,4 +23,59 @@ TBD
 Version Discovery
 -----------------
 
-TBD
+The Version API for each service should return the minimum and maximum
+versions. These values are used by the client to discover the supported API
+versions.
+
+A version response would look as follows. This example is from the compute API
+provided by Nova::
+
+    GET /
+    {
+         "versions": [
+            {
+                "id": "v2.1",
+                "links": [
+                      {
+                        "href": "http://localhost:8774/v2/",
+                        "rel": "self"
+                    }
+                ],
+                "status": "CURRENT",
+                "max_version": "5.2",
+                "min_version": "2.1"
+            },
+       ]
+    }
+
+"max_version" is maximum version, "min_version" is minimum version.
+
+When the requested version is out of range for the server, the server returns
+status code **406 Not Acceptable** along with a response body.
+
+The error response body conforms to the errors guideline :ref:`errors` with
+two additional properties as described in the json-schema below:
+
+::
+
+  {
+     "max_version": {
+      "type": "string", "pattern": "^([1-9]\d*)\.([1-9]\d*|0)$"
+     },
+     "min_version": {
+      "type": "string", "pattern": "^([1-9]\d*)\.([1-9]\d*|0)$"
+     }
+  }
+
+An example HTTP Header response:
+
+::
+
+  HTTP/1.1 406 Not Acceptable
+  Openstack-API-Version: compute 5.3
+  Vary: OpenStack-API-Version
+
+An example errors body response:
+
+.. literalinclude:: microversion-errors-example.json
+    :language: json