5.5 KiB
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.
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:
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:
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:
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:
https://git.openstack.org/cgit/openstack/api-wg/tree/guidelines/pagination_filter_sort.rst
ISO 8601 in Wikipedia: