A small set of functions to manage OpenStack microversion headers that can be used in middleware, application handlers and decorators to effectively manage microversions.

Also included, in the middleware module, is a MicroversionMiddleware that will process incoming microversion headers.


A simple parser for OpenStack microversion headers:

import microversion_parse

# headers is a dict of headers with folded (comma-separated
# values) or a list of header, value tuples
version = microversion_parse.get_version(
    headers, service_type='compute',

# If headers are not already available, a dict of headers
# can be extracted from the WSGI environ
headers = microversion_parse.headers_from_wsgi_environ(environ)
version = microversion_parse.get_version(
    headers, service_type='placement')

It processes microversion headers with the standard form:

OpenStack-API-Version: compute 2.1

In that case, the response will be ‘2.1’.

If provided with a legacy_headers argument, this is treated as a list of additional headers to check for microversions. Some examples of headers include:

OpenStack-telemetry-api-version: 2.1
OpenStack-nova-api-version: 2.1
X-OpenStack-nova-api-version: 2.1

If a version string cannot be found, None will be returned. If the input is incorrect usual Python exceptions (ValueError, TypeError) are allowed to raise to the caller.


A function to turn a version string into a Version, a comparable namedtuple:

version_tuple = microversion_parse.parse_version_string('2.1')

If the provided string is not a valid microversion string, TypeError is raised.


Combines get_version and parse_version_string to find and validate a microversion for a given service type in a collection of headers:

version_tuple = microversion_parse.extract_version(
    headers,  # a representation of headers, as accepted by get_version
    service_type,  # service type identify to match in headers
    versions_list,  # an ordered list of strings of version numbers that
                    # are the valid versions presented by this service

latest will be translated to whatever the max version is in versions_list.

If the found version is not in versions_list a ValueError is raised.

Note that extract_version does not support legacy_headers.


A WSGI middleware that can wrap an application that needs to be microversion aware. The application will get a WSGI environ with a ‘SERVICE_TYPE.microversion’ key that has a value of the microversion found at an ‘openstack-api-version’ header that matches SERVICE_TYPE. If no header is found, the minimum microversion will be set. If the special keyword ‘latest’ is used, the maximum microversion will be set.

If the requested microversion is not available a 406 response is returned.

If there is an error parsing a provided header, a 400 response is returned.

Otherwise the application is called.

The middleware is configured when it is created. Three parameters are required:


The next WSGI middleware or application in the stack.


The service type of the application, used to identify microversion headers.


An ordered list of legitimate microversions (as strings) for the application. It’s assumed that any application that is using microversions will have such a list for its own housekeeping and documentation.

One named parameter is optional:


A Webob error formatter that can be used to structure the response when JSON is expected.

For example:

def app():
    app = middleware.MicroversionMiddleware(
        MyWSGIApp(), 'cats', ['1.0', '1.1', '1.2'])
    return app

Indices and tables

Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.