openstack/api-sig
Code Issues Proposed changes
api-sig/guidelines/microversion_specification.rst
He Jie Xu 96700d724e Add version discover guideline for API microversions 
This guidelines describes how the client can request the
available microversions from the server.

Change-Id: I96a5084e5c44f030c19ed31f123b90cd184174b7
2016-03-14 14:58:08 +08:00

1.9 KiB
Raw Blame History

Microversion Specification

This topic document serves to provide guidance on how to work with microversions in OpenStack REST APIs.

Microversions enables the ability to introduce API changes while being able to allow clients to discover those changes. According to negotiations with servers, clients adjust their behavior to work with server correctly.

Versioning

TBD

Client Interaction

TBD

Version Discovery

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

microversion-errors-example.json