From d87f6b4537f37fb0e75d893927a7261ee77565d6 Mon Sep 17 00:00:00 2001 From: He Jie Xu Date: Wed, 6 Jan 2016 14:48:15 +0800 Subject: [PATCH] doc: add client interactive guideline for microversions This patch adds basic interactive guideline. blueprint complete-todo-in-api-concept-doc Change-Id: I3c828e34c43fa681328f71694940f05c87d28e06 --- api-guide/source/microversions.rst | 42 ++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/api-guide/source/microversions.rst b/api-guide/source/microversions.rst index ee8d4944808c..a8c138c77274 100644 --- a/api-guide/source/microversions.rst +++ b/api-guide/source/microversions.rst @@ -98,3 +98,45 @@ microversion to access the endpoint. You can also obtain specific endpoint version information by performing a GET on the base version URL (e.g., `http://openstack.example.com/v2.1/`). You can get more information about the version API at :doc:`versions`. + +Client Interaction +================== + +A client specifies the microversion of the API they want by using the following +HTTP header:: + + X-OpenStack-Nova-API-Version: 2.4 + +This acts conceptually like the "Accept" header. Semantically this means: + +* If `X-OpenStack-Nova-API-Version` is not provided, act as if the minimum + supported microversion was specified. + +* If `X-OpenStack-Nova-API-Version` is provided, respond with the API at + that microversion. If that's outside of the range of microversions supported, + return 406 Not Acceptable. + +* If `X-OpenStack-Nova-API-Version` is ``latest`` (special keyword), act as + if maximum was specified. + +.. warning:: The ``latest`` value is mostly meant for integration testing and + would be dangerous to rely on in client code since microversions are not + following semver and therefore backward compability is not guaranteed. + Clients should always require a specific microversion but limit what is + acceptable to the microversion range that it understands at the time. + +This means that out of the box, an old client without any knowledge of +microversions can work with an Openstack installation with microversions +support. + +Two extra headers are always returned in the response: + +* X-OpenStack-Nova-API-Version: microversion_number +* Vary: X-OpenStack-Nova-API-Version + +The first header specifies the microversion number of the API which was +executed. + +The second header is used as a hint to caching proxies that the response +is also dependent on the X-OpenStack-Nova-API-Version and not just +the body and query parameters. See :rfc:`2616` section 14.44 for details.