**************************
Containers API - Reference
**************************

GET /v1/containers
##################

Lists a project's containers.

Returned containers will be ordered by creation date; oldest to newest.

Parameters
**********

+--------+---------+------------------------------------------------------------+
| Name   | Type    | Description                                                |
+========+=========+============================================================+
| offset | integer | The starting index within the total list of the containers |
|        |         | that you would like to retrieve.                           |
+--------+---------+------------------------------------------------------------+
| limit  | integer | The maximum number of containers to return (up to 100).    |
|        |         | The default limit is 10.                                   |
+--------+---------+------------------------------------------------------------+

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

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

Request:
********

.. code-block:: javascript

    GET /v1/containers
    Headers:
        X-Auth-Token: <token>


Response:
*********

.. code-block:: javascript

    {
        "containers": [
            {
                "consumers": [],
                "container_ref": "https://{barbican_host}/v1/containers/{uuid}",
                "created": "2015-03-26T21:10:45.417835",
                "name": "container name",
                "secret_refs": [
                    {
                        "name": "private_key",
                        "secret_ref": "https://{barbican_host}/v1/secrets/{uuid}"
                    }
                ],
                "status": "ACTIVE",
                "type": "generic",
                "updated": "2015-03-26T21:10:45.417835"
            }
        ],
        "total": 1
    }


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

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

GET /v1/containers/{uuid}
#########################

Retrieves a single container.

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

+-------------+--------+---------------------------------------------------------+
| Name        | Type   | Description                                             |
+=============+========+=========================================================+
| name        | string | (optional) Human readable name for the container        |
+-------------+--------+---------------------------------------------------------+
| type        | string | Type of container. Options: generic, rsa, certificate   |
+-------------+--------+---------------------------------------------------------+
| secret_refs | list   | A list of dictionaries containing references to secrets |
+-------------+--------+---------------------------------------------------------+

Request:
********

.. code-block:: javascript

    GET /v1/containers/{uuid}
    Headers:
        X-Auth-Token: <token>

Response:
*********

.. code-block:: javascript

    {
        "type": "generic",
        "status": "ACTIVE",
        "name": "container name",
        "consumers": [],
        "container_ref": "https://{barbican_host}/v1/containers/{uuid}",
        "secret_refs": [
            {
                "name": "private_key",
                "secret_ref": "https://{barbican_host}/v1/secrets/{uuid}"
            }
        ],
        "created": "2015-03-26T21:10:45.417835",
        "updated": "2015-03-26T21:10:45.417835"
    }


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

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


POST /v1/containers
###################

Create a container

There are three different types of containers that can be created: generic,
rsa, and certificate.

**Generic**

This type of container holds any number of references to secrets. Each secret
reference is accompanied by a name. Unlike other container types, no specific
restrictions are enforced on the contents name attribute.

**RSA**

This type of container is designed to hold references to only three different
secrets. These secrets are enforced by their accompanied names: public_key,
private_key, and private_key_passphrase.

**Certificate**

This type of container is designed to hold a reference to a certificate and
optionally private_key, private_key_passphrase, and intermediates.

Request Attributes
******************

+-------------+--------+-----------------------------------------------------------+
| Name        | Type   | Description                                               |
+=============+========+===========================================================+
| name        | string | (optional) Human readable name for identifying your       |
|             |        | container                                                 |
+-------------+--------+-----------------------------------------------------------+
| type        | string | Type of container. Options: generic, rsa, certificate     |
+-------------+--------+-----------------------------------------------------------+
| secret_refs | list   | A list of dictionaries containing references to secrets   |
+-------------+--------+-----------------------------------------------------------+

Request:
********

.. code-block:: javascript

    POST /v1/containers
    Headers:
        X-Auth-Token: <token>

    Content:
    {
        "type": "generic",
        "name": "container name",
        "secret_refs": [
            {
                "name": "private_key",
                "secret_ref": "https://{barbican_host}/v1/secrets/{secret_uuid}"
            }
        ]
    }


Response:
*********

.. code-block:: javascript

    {
        "container_ref": "https://{barbican_host}/v1/containers/{container_uuid}"
    }


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

+------+-----------------------------------------------------------------------------+
| Code | Description                                                                 |
+======+=============================================================================+
| 201  | Successful creation of the container                                        |
+------+-----------------------------------------------------------------------------+
| 401  | Invalid X-Auth-Token or the token doesn't have permissions to this resource |
+------+-----------------------------------------------------------------------------+
| 403  | Forbidden.  The user has been authenticated, but is not authorized to       |
|      | create a container.  This can be based on the user's role or the            |
|      | project's quota.                                                            |
+------+-----------------------------------------------------------------------------+


DELETE /v1/containers/{uuid}
############################

Deletes a container

Request:
********

.. code-block:: javascript

    DELETE /v1/containers/{container_uuid}
    Headers:
        X-Auth-Token: <token>

Response:
*********

.. code-block:: javascript

    204 No Content

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

+------+-----------------------------------------------------------------------------+
| Code | Description                                                                 |
+======+=============================================================================+
| 204  | Successful deletion of a container                                          |
+------+-----------------------------------------------------------------------------+
| 401  | Invalid X-Auth-Token or the token doesn't have permissions to this resource |
+------+-----------------------------------------------------------------------------+
| 404  | Container not found or unavailable                                          |
+------+-----------------------------------------------------------------------------+

POST /v1/containers/{container_uuid}/secrets
############################################

Add a secret to an existing container.  This is only supported on generic
containers.

Request Attributes
******************

+------------+--------+------------------------------------------------------------+
| Name       | Type   | Description                                                |
+============+========+============================================================+
| name       | string | (optional) Human readable name for identifying your secret |
|            |        | within the container.                                      |
+------------+--------+------------------------------------------------------------+
| secret_ref | uri    | (required) Full URI reference to an existing secret.       |
+------------+--------+------------------------------------------------------------+

Request:
********

.. code-block:: javascript

    POST /v1/containers/{container_uuid}/secrets
    Headers:
        X-Project-Id: {project_id}

    Content:
    {
        "name": "private_key",
        "secret_ref": "https://{barbican_host}/v1/secrets/{secret_uuid}"
    }

Response:
*********

.. code-block:: javascript

    {
        "container_ref": "https://{barbican_host}/v1/containers/{container_uuid}"
    }

Note that the requesting 'container_uuid' is the same as that provided in the
response.


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

In general, error codes produced by the containers POST call pertain here as
well, especially in regards to the secret references that can be provided.

+------+-----------------------------------------------------------------------------+
| Code | Description                                                                 |
+======+=============================================================================+
| 201  | Successful update of the container                                          |
+------+-----------------------------------------------------------------------------+
| 400  | Missing secret_ref                                                          |
+------+-----------------------------------------------------------------------------+
| 401  | Invalid X-Auth-Token or the token doesn't have permissions to this resource |
+------+-----------------------------------------------------------------------------+
| 403  | Forbidden.  The user has been authenticated, but is not authorized to       |
|      | add the secret to the specified container.  This can be based on the user's |
|      | role or the project's quota.                                                |
+------+-----------------------------------------------------------------------------+

DELETE /v1/containers/{container_uuid}/secrets
##############################################

Remove a secret from a container.  This is only supported on generic
containers.

Request Attributes
******************

+------------+--------+------------------------------------------------------------+
| Name       | Type   | Description                                                |
+============+========+============================================================+
| name       | string | (optional) Human readable name for identifying your secret |
|            |        | within the container.                                      |
+------------+--------+------------------------------------------------------------+
| secret_ref | uri    | (required) Full URI reference to an existing secret.       |
+------------+--------+------------------------------------------------------------+

Request:
********

.. code-block:: javascript

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

   Content:
   {
       "name": "private key",
       "secret_ref": "https://{barbican_host}/v1/secrets/{secret_uuid}"
   }

Response:
*********

.. code-block:: javascript

   204 No Content

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

+------+-----------------------------------------------------------------------------+
| Code | Description                                                                 |
+======+=============================================================================+
| 204  | Successful removal of the secret from the container.                        |
+------+-----------------------------------------------------------------------------+
| 400  | Missing secret_ref                                                          |
+------+-----------------------------------------------------------------------------+
| 401  | Invalid X-Auth-Token or the token doesn't have permissions to this resource |
+------+-----------------------------------------------------------------------------+
| 403  | Forbidden.  The user has been authenticated, but is not authorized to       |
|      | remove the secret from the specified container.  This can be based on the   |
|      | user's role or the project's quota.                                         |
+------+-----------------------------------------------------------------------------+
| 404  | Specified secret_ref is not found in the container.                         |
+------+-----------------------------------------------------------------------------+
