Propose api-validation blueprint

This document describes the work required for adding a jsonschema
validation layer to the Zun API.

Partially-Implements: blueprint api-json-input-validation
Change-Id: Id7fecbef3aeb9a208b99c968f4ed4a60897403aa

specs/zun-api-validation.rst

@@ -0,0 +1,172 @@
+..
+ 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)