Blueprint for adding Date filters to the Secrets API
Change-Id: I3112415fa71a948202972bf60ae924922565d766
This commit is contained in:
parent
d93d91541a
commit
6f58e84a97
|
@ -0,0 +1,185 @@
|
||||||
|
..
|
||||||
|
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
||||||
|
License.
|
||||||
|
|
||||||
|
http://creativecommons.org/licenses/by/3.0/legalcode
|
||||||
|
|
||||||
|
==========================================
|
||||||
|
Date Filters
|
||||||
|
==========================================
|
||||||
|
|
||||||
|
https://blueprints.launchpad.net/barbican/+spec/date-filters
|
||||||
|
|
||||||
|
Problem Description
|
||||||
|
===================
|
||||||
|
|
||||||
|
In an effort to keep track of the changes being made to secrets or upcoming
|
||||||
|
expiration dates, users such as IT Auditors or Operations Engineers need to be
|
||||||
|
able to filter queries sent to the API based on the timestamped properties of a
|
||||||
|
secret. These users require new filters to be able to query information about
|
||||||
|
their secrets such as:
|
||||||
|
|
||||||
|
#. Secrets expiring in the near future
|
||||||
|
#. Secrets created in a particular time range
|
||||||
|
#. Secrets updated in a particular time range
|
||||||
|
|
||||||
|
Currently, Barbican does not provide any filters for querying secrets by
|
||||||
|
using the properties that hold timestamp values. So a user currently needs
|
||||||
|
to iterate through their entire secret collection to be able to gather this
|
||||||
|
data.
|
||||||
|
|
||||||
|
Proposed Change
|
||||||
|
===============
|
||||||
|
|
||||||
|
The barbican /secrets resource should be enhanced to allow sorting and
|
||||||
|
filtering based on a secret's ``created``, ``updated``, and ``expiration``
|
||||||
|
properties as described in the API Working Group's guideline for `Pagination,
|
||||||
|
Filtering, and Sorting`_
|
||||||
|
|
||||||
|
The filters should allow limiting of returned values to specific times and
|
||||||
|
time ranges by using the equality (``=``), greater-than (``gt``),
|
||||||
|
greater-than-or-equal (``gte``), less-than (``lt``), and
|
||||||
|
less-than-or-equal (``lte``) operators.
|
||||||
|
|
||||||
|
The filters should also allow the ordering of return values by using the
|
||||||
|
``sort`` query string parameter with both ascending (``asc``) and descending
|
||||||
|
(``desc``) directions for the specified sort key.
|
||||||
|
|
||||||
|
Values passed in to these query parameters are assumed to be give in UTC time
|
||||||
|
using the extended format described in ISO 8601. The UTC zone designation
|
||||||
|
represented by appending the "Z" character will be required. Values that do
|
||||||
|
not include the zone designation will result in an error response with status
|
||||||
|
code 400. Values that specify a time offset from UTC will also result in a 400
|
||||||
|
error response even if the offset is zero to specify UTC.
|
||||||
|
|
||||||
|
.. _Pagination, Filtering, and Sorting: http://git.openstack.org/cgit/openstack/api-wg/tree/guidelines/pagination_filter_sort.rst
|
||||||
|
|
||||||
|
Alternatives
|
||||||
|
------------
|
||||||
|
|
||||||
|
Requiring the zone designation for UTC ("Z") may be too stringent of a
|
||||||
|
requirement. One alternative would be to accept time values without the "Z"
|
||||||
|
zone designation and just assume that the values are all UTC.
|
||||||
|
|
||||||
|
Data model impact
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
This change will not affect the data model, since all values to be used in the
|
||||||
|
filtering are already part of the data model.
|
||||||
|
|
||||||
|
REST API impact
|
||||||
|
---------------
|
||||||
|
|
||||||
|
Additional query parameters will be available for the GET /v1/secrets resource
|
||||||
|
as described above.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
List secrets expiring in the next week (assuming current time is June 8, 2016
|
||||||
|
20:00 UTC) and sort by secrets expiring soonest:
|
||||||
|
|
||||||
|
.. code-block:: json
|
||||||
|
|
||||||
|
GET /v1/secrets?expiration=gt:2016-06-08T20:00:00Z,lt:2016-06-15T20:00:00Z&sort=expiration:asc
|
||||||
|
|
||||||
|
List secrets created in the previous week assuming same current time as above:
|
||||||
|
|
||||||
|
.. code-block:: json
|
||||||
|
|
||||||
|
GET /v1/secrets?created=gt:2016-06-01T20:00:00Z,lt:2016-06-08T20:00:00Z
|
||||||
|
|
||||||
|
List secrets updated in the previous week assuming same current time as above:
|
||||||
|
|
||||||
|
.. code-block:: json
|
||||||
|
|
||||||
|
GET /v1/secrets?updated=gt:2016-06-01T20:00:00Z,lt:2016-06-08T20:00:00Z
|
||||||
|
|
||||||
|
The format of the data in the request and response will not change.
|
||||||
|
|
||||||
|
Security impact
|
||||||
|
---------------
|
||||||
|
|
||||||
|
This change should not impact the security of barbican, since it just provides
|
||||||
|
a way to narrow the results of querying the API.
|
||||||
|
|
||||||
|
Notifications & Audit Impact
|
||||||
|
----------------------------
|
||||||
|
|
||||||
|
This change does not impact the notifications or auditing features of barbican.
|
||||||
|
|
||||||
|
Python and Command Line Client Impact
|
||||||
|
-------------------------------------
|
||||||
|
|
||||||
|
Both python-barbicanclient and the plugin for the unified CLI will need to be
|
||||||
|
updated to provide a way for clients to use these new filters.
|
||||||
|
|
||||||
|
Other end user impact
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
No additional end user impact should result from this change.
|
||||||
|
|
||||||
|
Performance Impact
|
||||||
|
------------------
|
||||||
|
|
||||||
|
The implementation should not use additional database queries, but rather use
|
||||||
|
the existing queries so that performance is not negatively impacted.
|
||||||
|
|
||||||
|
Other deployer impact
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
This change should not affect deployers.
|
||||||
|
|
||||||
|
Developer impact
|
||||||
|
----------------
|
||||||
|
|
||||||
|
Developers should not be impacted since these filters are optional. However,
|
||||||
|
developers could make use of these filters when applicable to their use
|
||||||
|
cases.
|
||||||
|
|
||||||
|
Implementation
|
||||||
|
==============
|
||||||
|
|
||||||
|
Assignee(s)
|
||||||
|
-----------
|
||||||
|
|
||||||
|
Primary assignee:
|
||||||
|
Douglas Mendizábal
|
||||||
|
|
||||||
|
Other contributors:
|
||||||
|
Joe Savak
|
||||||
|
|
||||||
|
Work Items
|
||||||
|
----------
|
||||||
|
|
||||||
|
#. Update controllers to accept and make use of the new filters
|
||||||
|
#. Update documentation to include the newly added filters
|
||||||
|
#. Update python-barbicanclient to make use of the new filters
|
||||||
|
#. Update the unified CLI plugin to make use of the new filters
|
||||||
|
|
||||||
|
Dependencies
|
||||||
|
============
|
||||||
|
|
||||||
|
None.
|
||||||
|
|
||||||
|
Testing
|
||||||
|
=======
|
||||||
|
|
||||||
|
New functional and unit tests that exercise the new functionality should be
|
||||||
|
included in the implementation of this spec.
|
||||||
|
|
||||||
|
Documentation Impact
|
||||||
|
====================
|
||||||
|
|
||||||
|
The API change will need to be updated in the API reference as well as the
|
||||||
|
user guide.
|
||||||
|
|
||||||
|
References
|
||||||
|
==========
|
||||||
|
|
||||||
|
API Working Group's Guideline for Pagination, Filtering and Sorting:
|
||||||
|
|
||||||
|
http://git.openstack.org/cgit/openstack/api-wg/tree/guidelines/pagination_filter_sort.rst
|
||||||
|
|
||||||
|
ISO 8601 in Wikipedia:
|
||||||
|
|
||||||
|
https://en.wikipedia.org/wiki/ISO_8601
|
Loading…
Reference in New Issue