# 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

# Indices and tables

- Index

- Module Index

- Search Page

this page last updated: 2026-03-31 07:35:02

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

found an error? report a bug