From 96700d724e6895271e599e92cd02c5c4760dda7c Mon Sep 17 00:00:00 2001
From: He Jie Xu <hejie.xu@intel.com>
Date: Tue, 10 Nov 2015 14:47:56 +0800
Subject: [PATCH] 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                       |  2 +
 guidelines/microversion-errors-example.json | 19 +++++++
 guidelines/microversion_specification.rst   | 57 ++++++++++++++++++++-
 3 files changed, 77 insertions(+), 1 deletion(-)
 create mode 100644 guidelines/microversion-errors-example.json

diff --git a/guidelines/errors.rst b/guidelines/errors.rst
index 73b83ff..4e31b9d 100644
--- a/guidelines/errors.rst
+++ b/guidelines/errors.rst
@@ -1,3 +1,5 @@
+.. _errors:
+
 Errors
 ======
 
diff --git a/guidelines/microversion-errors-example.json b/guidelines/microversion-errors-example.json
new file mode 100644
index 0000000..c54c46f
--- /dev/null
+++ b/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"
+                }
+             ]
+         }
+     ]
+}
diff --git a/guidelines/microversion_specification.rst b/guidelines/microversion_specification.rst
index e9e3f7d..1fee937 100644
--- a/guidelines/microversion_specification.rst
+++ b/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