..
 This work is licensed under a Creative Commons Attribution 3.0 Unported
 License.

 http://creativecommons.org/licenses/by/3.0/legalcode

==============
API Validation
==============

`bp api-json-input-validation <https://blueprints.launchpad.net/zun/+spec/api-json-input-validation>`_

The purpose of this blueprint is to track the progress of validating the
request bodies sent to the Zun API server, accepting requests
that fit the resource schema and rejecting requests that do not fit the
schema. Depending on the content of the request body, the request should
be accepted or rejected consistently regardless of the resource the request
is for.

Problem Description
===================

Currently Zun validates each type of resource in request body by defining a
type class for that resource, although such approach is good but is not very
scalable. It also require conversion of request body to controller object and
vice versa.

Use Case: As an End User, I want to observe consistent API validation and
values passed to the Zun API server.

Proposed Change
===============

One possible way to validate the Zun API is to use jsonschema
(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 to the resource manager. If the request body parameters fail the
validation specified by the resource schema, a validation error will be
returned from the server.

Example:
"Invalid input for field 'cpu'. The value is 'some invalid cpu value'.

We can build in some sort of truncation check if the value of the attribute is
too long. For example, if someone tries to pass in a 300 character name of
container we should check for that case and then only return a useful message,
instead of spamming the logs. Truncating some really long container name might
not help readability for the user, so return a message to the user with what
failed validation.

Example:
"Invalid input for field 'name'."

Some notes on doing this implementation:

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

    from zun.common.validation import parameter_types
    <snip>
    CREATE = {
        'type': 'object',
        'properties': {
            'name': parameter_types.name,
            'image': parameter_types.image,
            'command': parameter_types.command,
            <snip>
        },
        'required': ['image'],
        'additionalProperties': True,
    }

* The validation can take place at the controller layer.

* When adding a new extension to Zun, the new extension must be proposed
  with its appropriate schema.

Alternatives
------------

`Voluptuous <https://github.com/alecthomas/voluptuous>`_ might be another
option for input validation.

Data Model Impact
-----------------

This blueprint shouldn't require a database migration or schema change.

REST API Impact
---------------

This blueprint shouldn't affect the existing API.

Security Impact
---------------

None

Notifications Impact
--------------------

None

Other End User Impact
---------------------

None

Performance Impact
------------------

Changes required for request validation do not require any locking mechanisms.

Other Deployer Impact
---------------------

None

Developer Impact
----------------

This will require developers contributing new extensions to Zun to have
a proper schema representing the extension's API.

Implementation
==============

Assignee(s)
-----------

Primary assignee:
pksingh (Pradeep Kumar Singh <ps4openstack@gmail.com>)

Work Items
----------

1. Initial validator implementation, which will contain common validator code
   designed to be shared across all resource controllers validating request
   bodies.
2. Introduce validation schemas for existing core API resources.
3. Enforce validation on proposed core API additions and extensions.

Dependencies
============

None

Testing
=======

Tempest tests can be added as each resource is validated against its schema.

Documentation Impact
====================

None

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)