Open Stack

Hi,

I'd like to know what validation feature is really needed for Nova v3 API,
and I hope this mail will be a kick-off of brain-storming for it.

<< Introduction >>
I have submitted a blueprint "nova-api-validation-fw"[1].
The purpose is comprehensive validation of API input parameters.
32% of Nova v3 API parameters are not validated with any ways[2], and the
fact would cause an internal error if some clients just send an invalid 
request. If an internal error happens, the error message is output to a
log file and OpenStack operators should research its reason. It would be
hard work for the operators.

In Havana development cycle, I proposed the implementation code of the BP
but it was abandoned. Nova web framework will move to Pecan/WSME, but my
code depended on WSGI. So the code would have merits in short term, but not
in long term.
Now some Pecan/WSME sessions are proposed for Hong-Kong summit, so I feel
this situation is a good chance for this topic.

At the first step, I'd like to find what validation features are necessary
for Nova v3 API through the discussion. After listing necessary features, 
necessary features will be proposed for WSME improvement if we need.


For discussing, I have investigated all validation ways of current Nova v3
API parameters. There are 79 API methods, and 49 methods use API parameters
of a request body. Totally, they have 148 API parameters. (details: [3])

Necessary features, what I guess now, are the following:

<< Basic Validation Feature >>
Through this investigation, it seems that we need some basic validation
features such as:
* Type validation
  str(name, ..), int(vcpus, ..), float(rxtx_factor), dict(metadata, ..),
  list(networks, ..), bool(conbine, ..), None(availability_zone)
* String length validation
  1 - 255
* Value range validation
  value >= 0(rotation, ..), value > 0(vcpus, ..),
  value >= 1(os-multiple-create:min_count, os-multiple-create:max_count)
* Data format validation
  * Pattern:
    uuid(volume_id, ..), boolean(on_shared_storage, ..), base64encoded(contents),
    ipv4(access_ip_v4, fixed_ip), ipv6(access_ip_v6)
  * Allowed list:
    'active' or 'error'(state), 'parent' or 'child'(cells.type),
    'MANUAL' or 'AUTO'(os-disk-config:disk_config), ...
  * Allowed string:
    not contain '!' and '.'(cells.name),
    contain [a-zA-Z0-9_.- ] only(flavor.name, flavor.id)
* Mandatory validation
  * Required: server.name, flavor.name, ..
  * Optional: flavor.ephemeral, flavor.swap, ..


<< Auxiliary Validation Feature >>
Some parameters have a dependency between other parameter.
For example, name or/and availability_zone should be specified when updating an
aggregate. The parameter dependencies are few cases, and the dependency validation
feature would not be mandatory.

The cases are the following:
* Required if not specifying other:
  (update aggregate: name or availability_zone), (host: status or maintenance_mode),
  (server: os-block-device-mapping:block_device_mapping or image_ref)
* Should not specify both:
  (interface_attachment: net_id and port_id),
  (server: fixed_ip and port)


<< API Documentation Feature >>
WSME has a unique feature which generates API documentations from source code.
The documentations[4] contains:
* Method, URL (GET /v2/resources/, etc)
* Parameters
* Reterun type
* Parameter samples of both JSON and XML

This feature will help us for Nova v3 API, because it consists of many APIs and
the API sample implementations seemed hard processes in Havana development.
Current documentations, which are generated with this feature, contain only Type
as each parameter attribute.
If Nova-v3-API documentation contains String length, Value range, Data format,
Mandatory also, it help many developers and users.


Please let me know necessary features you are thinking.
Of course, any comments are welcome :-)


Thanks
Ken'ichi Ohmichi

---
[1]: https://blueprints.launchpad.net/nova/+spec/nova-api-validation-fw
[2]: https://wiki.openstack.org/wiki/NovaApiValidationFramework#Appendix:_Nova-v3-API_parameters 
[3]: https://wiki.openstack.org/wiki/NovaApiValidationFramework#What_is_necessary_for_Nova-v3-API
[4]: http://docs.openstack.org/developer/ceilometer/webapi/v2.html