<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Wed, Oct 16, 2013 at 1:19 PM, Ken'ichi Ohmichi <span dir="ltr"><<a href="mailto:ken1ohmichi@gmail.com" target="_blank">ken1ohmichi@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr">Hi Chris,<br><div class="gmail_extra"><br>Thank you for your response.</div>
<div class="gmail_extra"><br><div class="gmail_quote"><div class="im">2013/10/16 Christopher Yeoh <span dir="ltr"><<a href="mailto:cbkyeoh@gmail.com" target="_blank">cbkyeoh@gmail.com</a>></span><br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">
<div>On Tue, Oct 15, 2013 at 5:44 PM, Kenichi Oomichi <span dir="ltr"><<a href="mailto:oomichi@mxs.nes.nec.co.jp" target="_blank">oomichi@mxs.nes.nec.co.jp</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><br>
Hi,<br>
<br>
# I resend this because gmail distinguished my previous mail as spam one..<br>
<br>
I'd like to know what validation feature is really needed for Nova v3 API,<br>
and I hope this mail will be a kick-off of brain-storming for it.<br>
<br>
<< Introduction >><br>
I have submitted a blueprint "nova-api-validation-fw".<br>
The purpose is comprehensive validation of API input parameters.<br>
32% of Nova v3 API parameters are not validated with any ways[1], and the<br>
fact would cause an internal error if some clients just send an invalid<br>
request. If an internal error happens, the error message is output to a<br>
log file and OpenStack operators should research its reason. It would be<br>
hard work for the operators.<br>
<br></blockquote><div><br></div></div><div>We have tried to improve this for the V3 API but we still have a way to go. I believe a validation framework like you have proposed would be very useful - and cleanup the extension code.<br>
</div></div></div></div></blockquote><div><br></div></div><div>I'm really glad about this comment :-)</div><div><div class="h5"><div> </div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div>
</div><div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">In Havana development cycle, I proposed the implementation code of the BP<br>
but it was abandoned. Nova web framework will move to Pecan/WSME, but my<br>
code depended on WSGI. So the code would have merits in short term, but not<br>
in long term.<br>
Now some Pecan/WSME sessions are proposed for Hong-Kong summit, so I feel<br>
this situation is a good chance for this topic.<br>
<br></blockquote><div><br></div></div><div>I proposed the Nova Pecan/WSME session for the summit, but I do have a few reservations about whether the transition will be worth the pain I think will be involved. So I don't think its by any means clear that Pecan/WSME will be something we will do in Icehouse and your wsgi based implementation could be what we want to go ahead with. <br>
</div><div><div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">For discussing, I have investigated all validation ways of current Nova v3<br>
API parameters. There are 79 API methods, and 49 methods use API parameters<br>
of a request body. Totally, they have 148 API parameters. (details: [1])<br>
<br>
Necessary features, what I guess now, are the following:<br>
<br>
<< Basic Validation Feature >><br>
Through this investigation, it seems that we need some basic validation<br>
features such as:<br>
* Type validation<br>
str(name, ..), int(vcpus, ..), float(rxtx_factor), dict(metadata, ..),<br>
list(networks, ..), bool(conbine, ..), None(availability_zone)<br>
* String length validation<br>
1 - 255<br>
* Value range validation<br>
value >= 0(rotation, ..), value > 0(vcpus, ..),<br>
value >= 1(os-multiple-create:min_count, os-multiple-create:max_count)<br>
* Data format validation<br>
* Pattern:<br>
uuid(volume_id, ..), boolean(on_shared_storage, ..), base64encoded(contents),<br>
ipv4(access_ip_v4, fixed_ip), ipv6(access_ip_v6)<br>
* Allowed list:<br>
'active' or 'error'(state), 'parent' or 'child'(cells.type),<br>
'MANUAL' or 'AUTO'(os-disk-config:disk_config), ...<br>
* Allowed string:<br>
not contain '!' and '.'(<a href="http://cells.name" target="_blank">cells.name</a>),<br>
contain [a-zA-Z0-9_.- ] only(<a href="http://flavor.name" target="_blank">flavor.name</a>, <a href="http://flavor.id" target="_blank">flavor.id</a>)<br>
* Mandatory validation<br>
* Required: <a href="http://server.name" target="_blank">server.name</a>, <a href="http://flavor.name" target="_blank">flavor.name</a>, ..<br>
* Optional: flavor.ephemeral, flavor.swap, ..<br>
<br>
<br>
<< Auxiliary Validation Feature >><br>
Some parameters have a dependency between other parameter.<br>
For example, name or/and availability_zone should be specified when updating an<br>
aggregate. The parameter dependencies are few cases, and the dependency validation<br>
feature would not be mandatory.<br>
<br>
The cases are the following:<br>
* Required if not specifying other:<br>
(update aggregate: name or availability_zone), (host: status or maintenance_mode),<br>
(server: os-block-device-mapping:block_device_mapping or image_ref)<br>
* Should not specify both:<br>
(interface_attachment: net_id and port_id),<br>
(server: fixed_ip and port)<br>
<br></blockquote><div><br></div></div></div><div>These all sound useful.<br></div><div><div> <br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<< API Documentation Feature >><br>
WSME has a unique feature which generates API documentations from source code.<br>
The documentations(<a href="http://docs.openstack.org/developer/ceilometer/webapi/v2.html" target="_blank">http://docs.openstack.org/developer/ceilometer/webapi/v2.html</a>)<br>
contains:<br>
* Method, URL (GET /v2/resources/, etc)<br>
* Parameters<br>
* Reterun type<br>
* Parameter samples of both JSON and XML<br></blockquote><div><br></div></div><div>Do you know if the production of JSON/XML samples and integration of them into the api documentation<br></div><div>is all autogenerated via wsme?<br>
</div></div></div></div></blockquote><div><br></div></div></div><div>I'm not good at this feature.</div><div>but Ceilometer's document(<a href="http://docs.openstack.org/developer/ceilometer/webapi/v2.html" target="_blank">http://docs.openstack.org/developer/ceilometer/webapi/v2.html</a><span style="color:rgb(80,0,80)">) would be</span></div>
<div><span style="color:rgb(80,0,80)">generated </span><span style="color:rgb(80,0,80)">from </span><a href="https://github.com/openstack/ceilometer/blob/master/ceilometer/api/controllers/v2.py#L891" target="_blank">https://github.com/openstack/ceilometer/blob/master/ceilometer/api/controllers/v2.py#L891</a> etc.</div>
<div>API samples also would be autogenerated from sample() method.</div><div>I hope some experts will help us about this feature.<br></div></div></div></div></blockquote><div><br></div><div>The ceilometer developer docs are processed with sphinx, and the sample objects are turned from Python objects to XML or JSON and output in the HTML by sphinxcontrib-pecanwsme (naming packages is hard :-). There is also some work going on to generate the samples in the format that the doc team uses for the public documentation (<a href="https://review.openstack.org/#/c/45592/">https://review.openstack.org/#/c/45592/</a>), although it doesn't look like it is quite complete because the argument types aren't defined. I haven't seen the tool that is generating the WADL, yet.</div>
<div><br></div><div>Doug</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra">
<div class="gmail_quote"><div></div><div><div><br></div></div><div>The API sample implementations of Nova v3 API seemed very hard processes in Havana cycle.</div>
<div>There are a lot of API parameters, and some API parameter names are renamed to right ones.</div><div>Reviewers should check their name and the data types of API samples.</div><div>I feel this feature is good for Nova v3 API, but I'm not sure whether we should replace with Pecan/WSME in Icehouse.</div>
<div><br></div><div><br></div><div>Thanks</div><span class=""><font color="#888888"><div>Ken'ichi Ohmichi</div><div><br></div></font></span></div></div></div>
<br>_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
<br></blockquote></div><br></div></div>