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:

  1. Secrets expiring in the near future

  2. Secrets created in a particular time range

  3. 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.


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.


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.



Primary assignee:

Douglas Mendizábal

Other contributors:

Joe Savak

Work Items

  1. Update controllers to accept and make use of the new filters

  2. Update documentation to include the newly added filters

  3. Update python-barbicanclient to make use of the new filters

  4. Update the unified CLI plugin to make use of the new filters




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.


API Working Group’s Guideline for Pagination, Filtering and Sorting:

ISO 8601 in Wikipedia: