103 lines
3.4 KiB
ReStructuredText
103 lines
3.4 KiB
ReStructuredText
..
|
|
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
|
not use this file except in compliance with the License. You may obtain
|
|
a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
|
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
|
License for the specific language governing permissions and limitations
|
|
under the License.
|
|
|
|
|
|
Convention for heading levels in Neutron devref:
|
|
======= Heading 0 (reserved for the title in a document)
|
|
------- Heading 1
|
|
~~~~~~~ Heading 2
|
|
+++++++ Heading 3
|
|
''''''' Heading 4
|
|
(Avoid deeper levels because they do not render well.)
|
|
|
|
|
|
API Validators
|
|
==============
|
|
|
|
For the REST API, attributes may have custom validators defined. Each
|
|
validator will have a method to perform the validation, and a type
|
|
definition string, so that the validator can be referenced.
|
|
|
|
|
|
Defining A Validator Method
|
|
---------------------------
|
|
|
|
The validation method will have a positional argument for the data to
|
|
be validated, and may have additional (optional) keyword arguments that
|
|
can be used during validation. The method must handle any exceptions
|
|
and either return None (success) or a i18n string indicating the
|
|
validation failure message. By convention, the method name is prefixed
|
|
with ``validate_`` and then includes the data type. For example:
|
|
|
|
::
|
|
|
|
def validate_uuid(data, valid_values=None):
|
|
if not uuidutils.is_uuid_like(data):
|
|
msg = _("'%s' is not a valid UUID") % data
|
|
LOG.debug(msg)
|
|
return msg
|
|
|
|
There is a validation dictionary that maps the method to a validation
|
|
type that can be referred to in REST API definitions. An entry in the
|
|
dictionary would look like the following:
|
|
|
|
::
|
|
|
|
'type:uuid': validate_uuid,
|
|
|
|
|
|
Using Validators
|
|
----------------
|
|
|
|
In client code, the validator can be used in a REST API by using the
|
|
dictionary key for the validator. For example:
|
|
|
|
::
|
|
|
|
RESOURCE_ATTRIBUTE_MAP = {
|
|
NETWORKS: {
|
|
'id': {'allow_post': False, 'allow_put': False,
|
|
'validate': {'type:uuid': None},
|
|
'is_visible': True,
|
|
'primary_key': True},
|
|
'name': {'allow_post': True, 'allow_put': True,
|
|
'validate': {'type:string': NAME_MAX_LEN},
|
|
'default': '', 'is_visible': True},
|
|
|
|
Here, the networks resource has an 'id' attribute with a UUID validator,
|
|
as seen by the 'validate' key containing a dictionary with a key of
|
|
'type:uuid'.
|
|
|
|
Any addition arguments for the validator can be specified as values for
|
|
the dictionary entry (None in this case, NAME_MAX_LEN in the 'name'
|
|
attribute that uses a string validator). In a IP version attribute, one
|
|
could have a validator defined as follows:
|
|
|
|
::
|
|
|
|
'ip_version': {'allow_post': True, 'allow_put': False,
|
|
'convert_to': conversions.convert_to_int,
|
|
'validate': {'type:values': [4, 6]},
|
|
'is_visible': True},
|
|
|
|
Here, the validate_values() method will take the list of values as the
|
|
allowable values that can be specified for this attribute.
|
|
|
|
Test The Validator
|
|
------------------
|
|
|
|
Do the right thing, and make sure you've created a unit test for any
|
|
validator that you add to verify that it works as expected, even for
|
|
simple validators.
|
|
|