microversion_parse

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.

get_version

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',
    legacy_headers=['x-openstack-nova-api-version'])

# 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.

parse_version_string

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.

extract_version

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.

MicroversionMiddleware

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:

app

The next WSGI middleware or application in the stack.

service_type

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

versions_list

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:

json_error_formatter

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