Spec: Add ‘protected’ filter to image-list call

Change-Id: I9b57dccc18e7c7cb133cf0d1226a3f6bd35cb39f
APIImpact: new query parameter to existing call
This commit is contained in:
Brian Rosmaita 2017-03-29 16:47:52 -04:00 committed by Brian Rosmaita
parent 3c6f8c5ddb
commit 29ddb9a5d4
1 changed files with 186 additions and 0 deletions

View File

@ -0,0 +1,186 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
=========================================
Add 'protected' filter to image-list call
=========================================
https://blueprints.launchpad.net/glance/+spec/add-protected-filter
Images contain a boolean 'protected' field. Filtering on this field in the
image-list request is not currently supported. Operators and users who make
use of the 'protected' field to prevent accidental deletion of images, however,
would find such filtering useful. Not supporting filtering on this field is
counterintuitive as Glance supports filtering on all other image fields.
Problem description
===================
Use cases:
* An End User wants to list protected images that are accessible to that end
user.
* An End User wants to list non-protected images that are accessible to that
end user.
Proposed change
===============
Add code so that when 'protected=<value>' is included in a query string on the
image-list call, the value is converted to a boolean, making it suitable
for database filtering (the 'protected' field is a boolean in the database
backend).
For a user experience consistent with the image-create and image-update calls,
the only accepted values for this parameter will be 'true' or 'false' in that
exact case combination. Any other value for this parameter should return a 400
to indicate a bad request.
To summarize:
1. Introduce a new query parameter to the ``GET v2/images`` call, namely,
``protected``.
2. The parameter will act as a filter on the 'protected' field of an Image.
3. The set of values for the parameter will be strict, that is, the call will
accept only those strings that satisfy the JSON boolean data type (in other
words, only 'true' or 'false' in that exact case combination).
4. Unrecognized values will result in a 400 (Bad Request) response with an
appropriate message.
5. When the ``protected`` query parameter is not present, no filtering will be
done on the 'protected' field of Images. (In other words, there's no
default value.)
Alternatives
------------
1. Do nothing. This isn't really an option, because even though 'protected' is
not currently supported as a filter, image-list calls passing a value for
'protected' in the query string are accepted and do have an effect (the
API behaves as if ``protected=False`` has been specified). This behavior
appears weird to end users.
2. Implement the filter, but accept a liberal set of values, recognizing, for
example, 'true' or 'false' in any case combination; 'yes' or 'no' in any
case combination; and 1 or 0. This can be accomplished by using the oslo
string utilities, which contains a function ``bool_from_string`` that
converts strings to an appropriate boolean value [APF-1]_. Using the oslo
library has an additional bonus in that the usage will be consistent across
other OpenStack projects.
The downside to this alternative is that it is inconsistent with the
image-create and image-update calls in the Images v2 API. The latter calls
are governed by the Image json-schema, which clearly specifies a JSON
boolean type as the value of the ``protected`` field, and hence only 'true'
or 'false' in that exact case combination is what these calls accept. Thus,
liberal acceptance of commonly regarded boolean values in the query string
may cause API users to be surprised when these liberal values don't work for
image-create or image-update, leading to user dissatisfaction.
3. Implement the filter, but be extremely lax, that is, any value that isn't
mapped to the boolean value True by the oslo ``bool_from_string`` function
would be considered False. This actually isn't very user friendly. For
example, a French language speaker applying the query filter 'protected=oui'
will receive the complement of what was requested.
Data model impact
-----------------
None
REST API impact
---------------
This is a very minor modification to the ``GET v2/images`` call. The
only changes are:
* Parameters which can be passed via the URL now include ``protected``.
Security impact
---------------
None.
Notifications impact
--------------------
None.
Other end user impact
---------------------
The only impact on python-glanceclient is that the command
``glance image-list --property protected=true``
will now work correctly.
Performance Impact
------------------
None.
Other deployer impact
---------------------
None.
Developer impact
----------------
None.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
- fengzhr
Other contributors:
- rosmaita
- dharinic
Work Items
----------
* Implement the change roughly along the lines of
https://review.openstack.org/#/c/449108/
* Update the api-ref
* Write a release note
Dependencies
============
None.
Testing
=======
Functional tests consistent with the current image-list filtering tests.
Documentation Impact
====================
Small addition to the v2 image-list documentation in the api-ref.
References
==========
.. [APF-1] http://git.openstack.org/cgit/openstack/oslo.utils/tree/oslo_utils/strutils.py