diff --git a/specs/newton/date-filters.rst b/specs/newton/date-filters.rst new file mode 100644 index 0000000..bec6681 --- /dev/null +++ b/specs/newton/date-filters.rst @@ -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