diff --git a/specs/zun-api-validation.rst b/specs/zun-api-validation.rst new file mode 100644 index 000000000..896a23b16 --- /dev/null +++ b/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 `_ + +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 + + CREATE = { + 'type': 'object', + 'properties': { + 'name': parameter_types.name, + 'image': parameter_types.image, + 'command': parameter_types.command, + + }, + '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 `_ 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 ) + +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)