<commit_before>***********************
Secrets API - Reference
***********************

GET /secrets
############
Lists a project's secrets.

The list of secrets can be filtered by the parameters passed in via the URL.

Parameters
**********

+--------+---------+----------------------------------------------------------------+
| Name   | Type    | Description                                                    |
+========+=========+================================================================+
| offset | integer | The starting index within the total list of the secrets that   |
|        |         | you would like to retrieve.                                    |
+--------+---------+----------------------------------------------------------------+
| limit  | integer | The maximum number of records to return (up to 100). The       |
|        |         | default limit is 10.                                           |
+--------+---------+----------------------------------------------------------------+
| name   | string  | Selects all secrets with name equal to this value.             |
+--------+---------+----------------------------------------------------------------+
| bits   | integer | Selects all secrets with bit_length equal to this value.       |
+--------+---------+----------------------------------------------------------------+
| alg    | string  | Selects all secrets with algorithm equal to this value.        |
+--------+---------+----------------------------------------------------------------+
| mode   | string  | Selects all secrets with mode equal to this value.             |
+--------+---------+----------------------------------------------------------------+

Response Attributes
*******************

+----------+---------+--------------------------------------------------------------+
| Name     | Type    | Description                                                  |
+==========+=========+==============================================================+
| secrets  | list    | Contains a list of dictionaries filled with secret metadata. |
+----------+---------+--------------------------------------------------------------+
| total    | integer | The total number of secrets available to the user.           |
+----------+---------+--------------------------------------------------------------+
| next     | string  | A HATEOS url to retrieve the next set of secrets based on    |
|          |         | the offset and limit parameters. This attribute is only      |
|          |         | available when the total number of secrets is greater than   |
|          |         | offset and limit parameter combined.                         |
+----------+---------+--------------------------------------------------------------+
| previous | string  | A HATEOS url to retrieve the previous set of secrets based   |
|          |         | on the offset and limit parameters. This attribute is only   |
|          |         | available when the request offset is greater than 0.         |
+----------+---------+--------------------------------------------------------------+


HTTP Status Codes
*****************

+------+-----------------------------------------------------------------------------+
| Code | Description                                                                 |
+======+=============================================================================+
| 200  | Successful Request                                                          |
+------+-----------------------------------------------------------------------------+
| 401  | Invalid X-Auth-Token or the token doesn't have permissions to this resource |
+------+-----------------------------------------------------------------------------+


POST /secrets
#############
Creates a secret

Attributes
**********

+----------------------------+---------+----------------------------------------------+------------+
| Attribute Name             | Type    | Description                                  | Default    |
+============================+=========+==============================================+============+
| name                       | string  | (optional) The name of the secret set by the | None       |
|                            |         | user.                                        |            |
+----------------------------+---------+----------------------------------------------+------------+
| expiration                 | string  | (optional) This is a timestamp in ISO 8601   | None       |
|                            |         | format ``YYYY-MM-DDTHH:MM:SSZ.``             |            |
+----------------------------+---------+----------------------------------------------+------------+
| algorithm                  | string  | (optional) Metadata provided by a user or    | None       |
|                            |         | system for informational purposes.           |            |
+----------------------------+---------+----------------------------------------------+------------+
| bit_length                 | integer | (optional) Metadata provided by a user or    | None       |
|                            |         | system for informational purposes.           |            |
+----------------------------+---------+----------------------------------------------+------------+
| mode                       | string  | (optional) Metadata provided by a user or    | None       |
|                            |         | system for informational purposes.           |            |
+----------------------------+---------+----------------------------------------------+------------+
| payload                    | string  | (optional) The secret's data to be stored.   | None       |
|                            |         | ``payload_content_type`` must also be        |            |
|                            |         | supplied if payload is provided.             |            |
+----------------------------+---------+----------------------------------------------+------------+
| payload_content_type       | string  | (optional) (required if payload is added)    | None       |
|                            |         | The type and format of the secret data. The  |            |
|                            |         | two supported types are ``text/plain`` and   |            |
|                            |         | ``application/octet-stream``.                |            |
+----------------------------+---------+----------------------------------------------+------------+
| payload_content_encoding   | string  | (optional) The encoding used to format the   | None       |
|                            |         | payload provided. Currently only base64 is   |            |
|                            |         | supported. This is required if content type  |            |
|                            |         | provided has an encoding available.          |            |
+----------------------------+---------+----------------------------------------------+------------+
| secret_type                | string  | (optional) Used to indicate the type of      | ``opaque`` |
|                            |         | secret being stored. If no value is given,   |            |
|                            |         | ``opaque`` is used as the default, which is  |            |
|                            |         | used to signal Barbican to just store the    |            |
|                            |         | information without worrying about format or |            |
|                            |         | encoding.                                    |            |
+----------------------------+---------+----------------------------------------------+------------+

TODO(jvrbanac): Finish this section

GET /secrets/{uuid}
###################
Retrieves a secret's metadata by uuid

TODO(jvrbanac): Finish this section

DELETE /secrets/{uuid}
######################

Delete a secret by uuid

TODO(jvrbanac): Finish this section

GET /secrets/{uuid}/payload
###########################
Retrieve a secret's payload

TODO(jvrbanac): Finish this section

PUT /secrets/{uuid}/payload
###########################
Update a secret's payload

TODO(jvrbanac): Finish this section
<commit_msg>Adding more content to the api reference for secrets<commit_after>***********************
Secrets API - Reference
***********************

GET /v1/secrets
###############
Lists a project's secrets.

The list of secrets can be filtered by the parameters passed in via the URL.

The actual secret payload data will not be listed here. Clients must instead
make a separate call to get the secret details to view the secret.

Parameters
**********

+--------+---------+----------------------------------------------------------------+
| Name   | Type    | Description                                                    |
+========+=========+================================================================+
| offset | integer | The starting index within the total list of the secrets that   |
|        |         | you would like to retrieve.                                    |
+--------+---------+----------------------------------------------------------------+
| limit  | integer | The maximum number of records to return (up to 100). The       |
|        |         | default limit is 10.                                           |
+--------+---------+----------------------------------------------------------------+
| name   | string  | Selects all secrets with name equal to this value.             |
+--------+---------+----------------------------------------------------------------+
| bits   | integer | Selects all secrets with bit_length equal to this value.       |
+--------+---------+----------------------------------------------------------------+
| alg    | string  | Selects all secrets with algorithm equal to this value.        |
+--------+---------+----------------------------------------------------------------+
| mode   | string  | Selects all secrets with mode equal to this value.             |
+--------+---------+----------------------------------------------------------------+

Response Attributes
*******************

+----------+---------+--------------------------------------------------------------+
| Name     | Type    | Description                                                  |
+==========+=========+==============================================================+
| secrets  | list    | Contains a list of dictionaries filled with secret metadata. |
+----------+---------+--------------------------------------------------------------+
| total    | integer | The total number of secrets available to the user.           |
+----------+---------+--------------------------------------------------------------+
| next     | string  | A HATEOS url to retrieve the next set of secrets based on    |
|          |         | the offset and limit parameters. This attribute is only      |
|          |         | available when the total number of secrets is greater than   |
|          |         | offset and limit parameter combined.                         |
+----------+---------+--------------------------------------------------------------+
| previous | string  | A HATEOS url to retrieve the previous set of secrets based   |
|          |         | on the offset and limit parameters. This attribute is only   |
|          |         | available when the request offset is greater than 0.         |
+----------+---------+--------------------------------------------------------------+


HTTP Status Codes
*****************

+------+-----------------------------------------------------------------------------+
| Code | Description                                                                 |
+======+=============================================================================+
| 200  | Successful Request                                                          |
+------+-----------------------------------------------------------------------------+
| 401  | Invalid X-Auth-Token or the token doesn't have permissions to this resource |
+------+-----------------------------------------------------------------------------+


POST /v1/secrets
################
Creates a secret

Attributes
**********

+----------------------------+---------+----------------------------------------------+------------+
| Attribute Name             | Type    | Description                                  | Default    |
+============================+=========+==============================================+============+
| name                       | string  | (optional) The name of the secret set by the | None       |
|                            |         | user.                                        |            |
+----------------------------+---------+----------------------------------------------+------------+
| expiration                 | string  | (optional) This is a timestamp in ISO 8601   | None       |
|                            |         | format ``YYYY-MM-DDTHH:MM:SSZ``. Once this   |            |
|                            |         | time has past, the secret will no longer be  |            |
|                            |         | available.                                   |            |
+----------------------------+---------+----------------------------------------------+------------+
| algorithm                  | string  | (optional) Metadata provided by a user or    | None       |
|                            |         | system for informational purposes.           |            |
+----------------------------+---------+----------------------------------------------+------------+
| bit_length                 | integer | (optional) Metadata provided by a user or    | None       |
|                            |         | system for informational purposes. Value     |            |
|                            |         | must be greater than zero.                   |            |
+----------------------------+---------+----------------------------------------------+------------+
| mode                       | string  | (optional) Metadata provided by a user or    | None       |
|                            |         | system for informational purposes.           |            |
+----------------------------+---------+----------------------------------------------+------------+
| payload                    | string  | (optional) The secret's data to be stored.   | None       |
|                            |         | ``payload_content_type`` must also be        |            |
|                            |         | supplied if payload is provided.             |            |
+----------------------------+---------+----------------------------------------------+------------+
| payload_content_type       | string  | (optional) (required if payload is added)    | None       |
|                            |         | The type and format of the secret data. The  |            |
|                            |         | two supported types are ``text/plain`` and   |            |
|                            |         | ``application/octet-stream``.                |            |
+----------------------------+---------+----------------------------------------------+------------+
| payload_content_encoding   | string  | (optional) The encoding used to format the   | None       |
|                            |         | payload provided. Currently only base64 is   |            |
|                            |         | supported. This is required if content type  |            |
|                            |         | provided has an encoding available.          |            |
+----------------------------+---------+----------------------------------------------+------------+
| secret_type                | string  | (optional) Used to indicate the type of      | ``opaque`` |
|                            |         | secret being stored. If no value is given,   |            |
|                            |         | ``opaque`` is used as the default, which is  |            |
|                            |         | used to signal Barbican to just store the    |            |
|                            |         | information without worrying about format or |            |
|                            |         | encoding.                                    |            |
+----------------------------+---------+----------------------------------------------+------------+

Request:
********

.. code-block:: javascript

    POST /v1/secrets
    Headers:
        Content-Type: application/json
        X-Project-Id: {project_id}

    Content:
    {
        "name": "AES key",
        "expiration": "2015-12-28T19:14:44.180394",
        "algorithm": "aes",
        "bit_length": 256,
        "mode": "cbc",
        "payload": "YmVlcg==",
        "payload_content_type": "application/octet-stream",
        "payload_content_encoding": "base64"
    }

Response:
*********

.. code-block:: javascript

    201 Created

    {
        "secret_ref": "https://{barbican_host}/v1/secrets/{secret_uuid}"
    }


HTTP Status Codes
*****************

+------+-----------------------------------------------------------------------------+
| Code | Description                                                                 |
+======+=============================================================================+
| 201  | Successfully created a Secret                                               |
+------+-----------------------------------------------------------------------------+
| 400  | Bad Request                                                                 |
+------+-----------------------------------------------------------------------------+
| 401  | Invalid X-Auth-Token or the token doesn't have permissions to this resource |
+------+-----------------------------------------------------------------------------+
| 415  | Unsupported media-type                                                      |
+------+-----------------------------------------------------------------------------+


GET /v1/secrets/{uuid}
######################
Retrieves a secret's metadata or payload via uuid.

The return type of content, metadata or payload, is controlled by the Accept
header.

Accept Header Options:
**********************

* application/json - Returns secret metadata
* application/octet-stream - Returns secret payload
* text/plain - Returns secret payload


Metadata Request:
*****************

.. code-block:: javascript

    GET /v1/secrets/{uuid}
    Headers:
        Accept: application/json
        X-Project-Id: {project_id}


Metadata Response:
******************

.. code-block:: javascript

    200 OK

    {
        "status": "ACTIVE",
        "created": "2015-03-23T20:46:51.650515",
        "updated": "2015-03-23T20:46:51.654116",
        "expiration": "2015-12-28T19:14:44.180394",
        "algorithm": "aes",
        "bit_length": 256,
        "mode": "cbc",
        "name": "AES key",
        "secret_ref": "https://{barbican_host}/v1/secrets/{secret_uuid}",
        "secret_type": "opaque",
        "content_types": {
            "default": "application/octet-stream"
        }
    }

Payload Request:
****************

.. code-block:: javascript

    GET /v1/secrets/{uuid}
    Headers:
        Accept: application/octet-stream
        X-Project-Id: {project_id}


Payload Response:
*****************

.. code-block:: javascript

    200 OK

    beer


HTTP Status Codes
*****************

+------+-----------------------------------------------------------------------------+
| Code | Description                                                                 |
+======+=============================================================================+
| 200  | Successful request                                                          |
+------+-----------------------------------------------------------------------------+
| 401  | Invalid X-Auth-Token or the token doesn't have permissions to this resource |
+------+-----------------------------------------------------------------------------+
| 404  | Not Found                                                                   |
+------+-----------------------------------------------------------------------------+
| 406  | Not Acceptable                                                              |
+------+-----------------------------------------------------------------------------+

PUT /v1/secrets/{uuid}
######################

Update a secret's payload by uuid

.. note::

    This action can only be done for a secret that doesn't have a payload already
    set.

Required Headers
****************

+------------------+---------------------------------------------------+------------+
| Name             | Description                                       | Default    |
+==================+===================================================+============+
| Content-Type     | Corresponds with the payload_content_type         | text/plain |
|                  | attribute of a normal secret creation request.    |            |
+------------------+---------------------------------------------------+------------+
| Content-Encoding | Corresponds with the payload_content_encoding     | None       |
|                  | attribute of a normal secret creation request.    |            |
+------------------+---------------------------------------------------+------------+

Request:
********

.. code-block:: javascript

    PUT /v1/secrets/{uuid}
    Headers:
        X-Project-Id: {project_id}
        Content-Type: application/octet-stream
        Content-Encoding: base64

    Content:
    YmxhaA==

Response:
*********

.. code-block:: javascript

    204 No Content

HTTP Status Codes
*****************

+------+-----------------------------------------------------------------------------+
| Code | Description                                                                 |
+======+=============================================================================+
| 204  | Successful request                                                          |
+------+-----------------------------------------------------------------------------+
| 401  | Invalid X-Auth-Token or the token doesn't have permissions to this resource |
+------+-----------------------------------------------------------------------------+
| 404  | Not Found                                                                   |
+------+-----------------------------------------------------------------------------+


DELETE /v1/secrets/{uuid}
#########################

Delete a secret by uuid

Request:
****************

.. code-block:: javascript

    DELETE /v1/secrets/{uuid}
    Headers:
        X-Project-Id: {project_id}

Response:
****************

.. code-block:: javascript

    204 No Content

HTTP Status Codes
*****************

+------+-----------------------------------------------------------------------------+
| Code | Description                                                                 |
+======+=============================================================================+
| 204  | Successful request                                                          |
+------+-----------------------------------------------------------------------------+
| 401  | Invalid X-Auth-Token or the token doesn't have permissions to this resource |
+------+-----------------------------------------------------------------------------+
| 404  | Not Found                                                                   |
+------+-----------------------------------------------------------------------------+


GET /v1/secrets/{uuid}/payload
##############################
Retrieve a secret's payload

TODO(jvrbanac): Finish this section

PUT /v1/secrets/{uuid}/payload
##############################
Update a secret's payload

TODO(jvrbanac): Finish this section

{'fraction_non_alphanumeric': 0.3893805309734513, 'fraction_numerical': 0.008184802027504259, 'mean_word_length': 0.7749428508222107, 'pattern_counts': {'":': 21, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 107, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '653675', 'n_tokens_mistral': 4519, 'n_tokens_neox': 4161, 'n_words': 1283}