API Validation¶

Problem description¶

Currently Karbor doesn’t have a consistent request validation layer. Some resources validate input at the resource controller and some fail out in the backend. Ideally, Karbor would have some validation in place to catch disallowed parameters and return a validation error to the user.

The end user will benefit from having consistent and helpful feedback, regardless of which resource they are interacting with.

Use Cases¶

As a user or developer, I want to observe consistent API validation and values passed to the Karbor API server.

Proposed change¶

One possible way to validate the Karbor API is to use jsonschema similar to Nova, Keystone and Glance (https://pypi.python.org/pypi/jsonschema). A jsonschema validator object can be used to check each resource against an appropriate schema for that resource. If the validation passes, the request can follow the existing flow of control through the resource manager to the backend. If the request body parameters fails the validation specified by the resource schema, a validation error wrapped in HTTPBadRequest will be returned from the server.

Example: “Invalid input for field ‘name’. The value is ‘some invalid name value’.

Each API definition should be added with the following ways:

• Create definition files under ./karbor/api/schemas/.
• Each definition should be described with JSON Schema.
• Each parameter of definitions(type, minLength, etc.) can be defined from current validation code, DB schema, unit tests, or so on.

Some notes on doing this implementation:

• Common parameter types can be leveraged across all Karbor resources. An example of this would be as follows:

  from karbor.api.validation import parameter_types
  # plan create schema
  <snip>
       create = {
          'type': 'object',
          'properties': {
              'type': 'object',
              'plan': {
                  'type': 'object',
                  'properties': {
                      'name': parameter_types.name,
                      'description': parameter_types.description,
                      'provider_id': parameter_types.uuid,
                      'parameters': parameter_types.metadata,
                      'resources': parameter_types.metadata,
                  },
                  'required': ['provider_id', 'parameters'],
                  'additionalProperties': False,
              },
          },
          'required': ['plan'],
          'additionalProperties': False,
      }
  
  parameter_types.py:
  
  name = {
      'type': 'string', 'minLength': 0, 'maxLength': 255,
  }
  
  description = {
      'type': ['string', 'null'], 'minLength': 0, 'maxLength': 255,
      'pattern': valid_description_regex,
  }
  
  uuid = {
      'type': 'string', 'format': 'uuid'
  }
  
  # This registers a FormatChecker on the jsonschema module.
  # It might appear that nothing is using the decorated method but it gets
  # used in JSON schema validations to check uuid formatted strings.
  from oslo_utils import uuidutils
  
  @jsonschema.FormatChecker.cls_checks('uuid')
  def _validate_uuid_format(instance):
      return uuidutils.is_uuid_like(instance)
  

• The validation can take place at the controller layer using below decorator:

  from karbor.api.schemas import plans as plan
  
  @validation.schema(plan.create)
  def create(self, req, body):
      """Creates a new plan."
  

• When adding a new API resources to Karbor, the new resource must be proposed with its appropriate schema.

Implementation¶

Dependencies¶

None

Testing¶

Some tests can be added as each resource is validated against its schema. These tests should walk through invalid request types.

Documentation Impact¶

1. The Karbor API documentation will need to be updated to reflect the REST API changes.
2. The Karbor developer documentation will need to be updated to explain how the schema validation will work and how to add json schema for new API’s.

References¶

Useful Links:

• [Understanding JSON Schema] (http://spacetelescope.github.io/understanding-json-schema/reference/object.html)
• [Nova Validation Examples] (http://git.openstack.org/cgit/openstack/nova/tree/nova/api/validation)
• [JSON Schema on PyPI] (https://pypi.python.org/pypi/jsonschema)
• [JSON Schema core definitions and terminology] (http://tools.ietf.org/html/draft-zyp-json-schema-04)
• [JSON Schema Documentation] (http://json-schema.org/documentation.html)