API Documentation for user password expires

New proposal on how we document the password_expires_at query.

bp pci-dss-query-password-expired-users

Co-Authored-By: Samuel Pilla <sp516w@att.com>

Change-Id: I81facd0a84f5c05f72294eb1a143c7632b2406e1

api-ref/source/v3/groups.inc

@@ -302,6 +302,7 @@ Request Parameters
 .. rest_parameters:: parameters.yaml
 
    - group_id: group_id_path
+   - password_expires_at: password_expires_at_query
 
 Response Example
 ----------------

api-ref/source/v3/index.rst

@@ -27,6 +27,8 @@ What's New in Version 3.8
 =========================
 
 - Allow a service user to fetch a token that has expired.
+- Add a ``password_expires_at`` query parameter to user list and users in
+  group list.
 
 What's New in Version 3.7
 =========================

api-ref/source/v3/parameters.yaml

@@ -285,6 +285,35 @@ parents_as_list:
   required: false
   type: key-only, no value expected
   min_version: 3.4
+password_expires_at_query:
+  description: |
+    Filter results based on which user passwords have expired. The query should
+    include an ``operator`` and a ``timestamp`` with a colon (``:``) separating
+    the two, for example::
+
+      password_expires_at={operator}:{timestamp}
+
+    - Valid operators are: ``lt``, ``lte``, ``gt``, ``gte``, ``eq``, and ``neq``
+
+      - lt: expiration time lower than the timestamp
+      - lte: expiration time lower than or equal to the timestamp
+      - gt: expiration time higher than the timestamp
+      - gte: expiration time higher than or equal to the timestamp
+      - eq: expiration time equal to the timestamp
+      - neq: expiration time not equal to the timestamp
+
+    - Valid timestamps are of the form: ``YYYY-MM-DDTHH:mm:ssZ``.
+
+    For example::
+
+      /v3/users?password_expires_at=lt:2016-12-08T22:02:00Z
+
+    The example would return a list of users whose password expired before the
+    timestamp (``2016-12-08T22:02:00Z``).
+
+  in: query
+  required: false
+  type: string
 policy_type_query:
   description: |
     Filters the response by a MIME media type for the

api-ref/source/v3/users.inc

@@ -47,6 +47,7 @@ Request Parameters
    - domain_id: domain_id_query
    - enabled: enabled_user_query
    - name: name_user_query
+   - password_expires_at: password_expires_at_query
 
 Response Parameters
 -------------------