# API Converters

Definitions for REST API attributes, can include conversion methods to help normalize user input or transform the input into a form that can be used.

## Defining A Converter Method

By convention, the name should start with `convert_to_`, and will take a single argument for the data to be converted. The method should return the converted data (which, if the input is None, and no conversion is performed, the implicit None returned by the method may be used). If the conversion is impossible, an InvalidInput exception should be raised, indicating what is wrong. For example, here is one that converts a variety of user inputs to a boolean value.

    def convert_to_boolean(data):
         if isinstance(data, str):
             val = data.lower()
             if val == "true" or val == "1":
                 return True
             if val == "false" or val == "0":
                 return False
         elif isinstance(data, bool):
             return data
         elif isinstance(data, int):
             if data == 0:
                 return False
             elif data == 1:
                 return True
         msg = _("'%s' cannot be converted to boolean") % data
         raise n_exc.InvalidInput(error_message=msg)

## Using Validators

In client code, the conversion can be used in a REST API definition, by specifying the name of the method as a value for the ‘convert_to’ key on an attribute. For example:

    'admin_state_up': {'allow_post': True, 'allow_put': True,
                       'default': True,
                       'convert_to': conversions.convert_to_boolean,
                       'is_visible': True},

Here, the admin_state_up is a boolean, so the converter is used to take user’s (string) input and transform it to a boolean.

## Test The Validator

Do the right thing, and make sure you’ve created a unit test for any converter that you add to verify that it works as expected.

## IPv6 canonical address formatter

There are several ways to display an IPv6 address, which can lead to a lot of confusion for users, engineers and operators alike. To reduce the impact of the multifaceted style of writing an IPv6 address, it is proposed that the IPv6 address in Neutron should be saved in the canonical format.

If a user passes an IPv6 address, it will be saved in the canonical format.

The full document is found at : http://tools.ietf.org/html/rfc5952

this page last updated: 2026-03-26 12:58:28

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