***********************
Orders API - User Guide
***********************

The orders resource allows the user to request barbican to generate a secret.
This is also very helpful for requesting the creation of public/private key pairs.

The orders resource supports the following types:
    * symmetric keys
    * asymmetric keys

This user guide provides high level examples of the orders resource.
It will assume you will be using a local running development environment of barbican.
If you need assistance with getting set up, please reference the
`development guide <https://docs.openstack.org/barbican/latest/contributor/dev.html>`__.

.. _create_order:

Creating an Order
#################

When you want barbican to generate a secret you need to create an order.
For an order to be processed correctly the parameters mode,
bit_length, and algorithm must be valid. Otherwise the order will fail and
the secret will not be generated. The example below shows a valid order for
generating a symmetric key. You can find a more detailed explanation about
the parameters in the
`Orders API <https://docs.openstack.org/barbican/latest/api/reference/orders.html>`__
documentation.

.. code-block:: bash

    curl -X POST -H "X-Auth-Token: $TOKEN" -H "content-type:application/json" -d '{
    "type":"key", "meta": { "name": "secretname", "algorithm": "aes",
    "bit_length": 256, "mode": "cbc", "payload_content_type": "application/octet-stream"}
    }' http://localhost:9311/v1/orders

You should receive an order reference after placing your order with barbican.

.. code-block:: bash

    {"order_ref": "http://localhost:9311/v1/orders/3a5c6748-44de-4c1c-9e54-085c3f79e942"}

The order reference is used to retrieve the metadata for the order you placed
which can then be used to retrieve your secret.

.. _retrieve_order:

Retrieving an Order
###################

In order to retrieve the order we will use the reference returned during
the initial creation. (See :ref:`Creating an Order <create_order>`.)

.. code-block:: bash

    curl -H "X-Auth-Token: $TOKEN" -H 'Accept:application/json' \
    http://localhost:9311/v1/orders/3a5c6748-44de-4c1c-9e54-085c3f79e942

The typical response is below:

.. code-block:: json

    {
        "created": "2015-10-15T18:15:10",
        "creator_id": "40540f978fbd45c1af18910e3e02b63f",
        "meta": {
            "algorithm": "AES",
            "bit_length": 256,
            "expiration": null,
            "mode": "cbc",
            "name": "secretname",
            "payload_content_type": "application/octet-stream"
        },
        "order_ref": "http://localhost:9311/v1/orders/3a5c6748-44de-4c1c-9e54-085c3f79e942",
        "secret_ref": "http://localhost:9311/v1/secrets/bcd1b853-edeb-4509-9f12-019b8c8dfb5f",
        "status": "ACTIVE",
        "sub_status": "Unknown",
        "sub_status_message": "Unknown",
        "type": "key",
        "updated": "2015-10-15T18:15:10"
    }

This is the metadata associated with the order.
To retrieve the secret generated by the order, refer to the :doc:`Secrets User Guide <secrets>`.
The order metadata is very useful for determining if your order was processed
correctly. Since orders are processed asynchronously, you can use the metadata
returned for the order to verify a successful secret creation.
The parameters of the response are explained in more detail
`here <https://docs.openstack.org/barbican/latest/api/reference/orders.html#get-unique-order-response-attributes>`__.

.. _retrieve_order_list:

Retrieving All Orders
#####################

It is also possible to retrieve all orders for a project.

.. code-block:: bash

    curl -H "X-Auth-Token: $TOKEN" -H 'Accept:application/json' http://localhost:9311/v1/orders

.. code-block:: json

    {
        "orders": [
            {
                "created": "2015-10-15T18:15:10",
                "creator_id": "40540f978fbd45c1af18910e3e02b63f",
                "meta": {
                    "algorithm": "AES",
                    "bit_length": 256,
                    "expiration": null,
                    "mode": "cbc",
                    "name": "secretname",
                    "payload_content_type": "application/octet-stream"
                },
                "order_ref": "http://localhost:9311/v1/orders/3a5c6748-44de-4c1c-9e54-085c3f79e942",
                "secret_ref": "http://localhost:9311/v1/secrets/bcd1b853-edeb-4509-9f12-019b8c8dfb5f",
                "status": "ACTIVE",
                "sub_status": "Unknown",
                "sub_status_message": "Unknown",
                "type": "key",
                "updated": "2015-10-15T18:15:10"
            },
            {
                "created": "2015-10-15T18:51:35",
                "creator_id": "40540f978fbd45c1af18910e3e02b63f",
                "meta": {
                    "algorithm": "AES",
                    "bit_length": 256,
                    "mode": "cbc",
                    "expiration": null,
                    "name": null
                },
                "order_ref": "http://localhost:9311/v1/orders/d99ced51-ea7a-4c14-8e11-0dda0f49c5be",
                "secret_ref": "http://localhost:9311/v1/secrets/abadd306-8235-4f6b-984a-cc48ad039def",
                "status": "ACTIVE",
                "sub_status": "Unknown",
                "sub_status_message": "Unknown",
                "type": "key",
                "updated": "2015-10-15T18:51:35"
            }
        ],
        "total": 2
    }

You can refer to the
`orders parameters <https://docs.openstack.org/barbican/latest/api/reference/orders.html#get-order-parameters>`__
section of the
`Orders API <https://docs.openstack.org/barbican/latest/api/reference/orders.html>`__
documentation in order to refine your search among orders.

.. _delete_order:

Deleting an Order
#################

It is also possible to delete an order from barbican.

.. code-block:: bash

    curl -X DELETE -H "X-Auth-Token: $TOKEN" -H 'Accept:application/json' http://localhost:9311/v1/orders/fbdd845f-4a5e-43e3-8f68-64e8f106c486

Nothing will be returned when you delete an order.
If something was returned there was most likely an error while deleting
the order.