diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst index 2affb66c6..f5bf29eb8 100644 --- a/doc/source/api/index.rst +++ b/doc/source/api/index.rst @@ -3,7 +3,7 @@ Barbican API Documentation ************************** User Guide -########### +########## .. toctree:: :maxdepth: 1 @@ -17,6 +17,7 @@ User Guide ./userguide/dogtag_setup ./userguide/quotas ./userguide/consumers + ./userguide/orders API Reference ############# @@ -31,3 +32,4 @@ API Reference ./reference/cas ./reference/quotas ./reference/consumers + ./reference/orders diff --git a/doc/source/api/reference/orders.rst b/doc/source/api/reference/orders.rst new file mode 100644 index 000000000..4ffcef208 --- /dev/null +++ b/doc/source/api/reference/orders.rst @@ -0,0 +1,364 @@ +********************** +Orders API - Reference +********************** + +.. _get_orders: + +GET /v1/orders +############## +Lists a project's orders. + +The list of orders can be filtered by the parameters passed in via the URL. + +.. _get_order_parameters: + +Parameters +********** + ++----------+---------+----------------------------------------------------------------+ +| Name | Type | Description | ++==========+=========+================================================================+ +| offset | integer | The starting index within the total list of the orders that | +| | | you would like to retrieve. (Default is 0) | ++----------+---------+----------------------------------------------------------------+ +| limit | integer | The maximum number of records to return (up to 100). | +| | | (Default is 10) | ++----------+---------+----------------------------------------------------------------+ + +.. _get_orders_request: + +Request: +******** + +.. code-block:: javascript + + GET /v1/orders + Headers: + Content-Type: application/json + X-Auth-Token: {token} + +.. _get_orders_response: + +Response: +********* + +.. code-block:: none + + 200 Success + + { + "orders": [ + { + "created": "2015-10-20T18:38:44", + "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/2284ba6f-f964-4de7-b61e-c413df5d1e47", + "secret_ref": "http://localhost:9311/v1/secrets/15dcf8e4-3138-4360-be9f-fc4bc2e64a19", + "status": "ACTIVE", + "sub_status": "Unknown", + "sub_status_message": "Unknown", + "type": "key", + "updated": "2015-10-20T18:38:44" + }, + { + "created": "2015-10-20T18:38:47", + "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/87b7169e-3aa2-4cb1-8800-b5aadf6babd1", + "secret_ref": "http://localhost:9311/v1/secrets/80183f4b-c0de-4a94-91ad-6d55251acee2", + "status": "ACTIVE", + "sub_status": "Unknown", + "sub_status_message": "Unknown", + "type": "key", + "updated": "2015-10-20T18:38:47" + } + ], + "total": 2 +} + + +.. _get_order_response_attributes: + +Response Attributes +******************* + ++----------+---------+--------------------------------------------------------------+ +| Name | Type | Description | ++==========+=========+==============================================================+ +| orders | list | Contains a list of dictionaries filled with order metadata. | ++----------+---------+--------------------------------------------------------------+ +| total | integer | The total number of orders available to the user. | ++----------+---------+--------------------------------------------------------------+ +| next | string | A HATEOS url to retrieve the next set of objects based on | +| | | the offset and limit parameters. This attribute is only | +| | | available when the total number of objects is greater than | +| | | offset and limit parameter combined. | ++----------+---------+--------------------------------------------------------------+ +| previous | string | A HATEOS url to retrieve the previous set of objects based | +| | | on the offset and limit parameters. This attribute is only | +| | | available when the request offset is greater than 0. | ++----------+---------+--------------------------------------------------------------+ + +.. _get_order_status_codes: + +HTTP Status Codes +***************** + ++------+-----------------------------------------------------------------------------+ +| Code | Description | ++======+=============================================================================+ +| 200 | Successful Request | ++------+-----------------------------------------------------------------------------+ +| 401 | Invalid X-Auth-Token or the token doesn't have permissions to this resource | ++------+-----------------------------------------------------------------------------+ + +.. _post_orders: + +POST /v1/orders +############### +Creates an order + +Parameters +********** + ++----------------------------+---------+----------------------------------------------+------------+ +| Attribute Name | Type | Description | Default | ++============================+=========+==============================================+============+ +| type | string | The type of key to be generated. Valid types | None | +| | | are key, asymmetric, and certificate | | ++----------------------------+---------+----------------------------------------------+------------+ +| meta | | Dictionary containing the secret metadata | None | +| | dict | used to generate the secret. | | +| | | | | ++----------------------------+---------+----------------------------------------------+------------+ + +.. _post_orders_request: + +Request: +******** + +.. code-block:: javascript + + POST /v1/orders + Headers: + Content-Type: application/json + X-Auth-Token: {token} + + Content: + { + "type":"key", + "meta": + { + "name":"secretname", + "algorithm": "AES", + "bit_length": 256, + "mode": "cbc", + "payload_content_type":"application/octet-stream" + } + } + +.. _post_orders_response: + +Response: +********* + +.. code-block:: none + + 202 Created + + { + "order_ref": "http://{barbican_host}/v1/orders/{order_uuid}" + } + +.. _post_orders_response_attributes: + +Response Attributes +******************* + ++----------+---------+--------------------------------------------------------------+ +| Name | Type | Description | ++==========+=========+==============================================================+ +| order_ref| string | Order reference | ++----------+---------+--------------------------------------------------------------+ + +.. _post_orders_status_codes: + +HTTP Status Codes +***************** + ++------+-----------------------------------------------------------------------------+ +| Code | Description | ++======+=============================================================================+ +| 202 | Successfully created an order | ++------+-----------------------------------------------------------------------------+ +| 400 | Bad Request | ++------+-----------------------------------------------------------------------------+ +| 401 | Invalid X-Auth-Token or the token doesn't have permissions to this resource | ++------+-----------------------------------------------------------------------------+ +| 415 | Unsupported media-type | ++------+-----------------------------------------------------------------------------+ + +.. _get_unique_order_metadata: + +GET /v1/orders/{uuid} +##################### +Retrieves an order's metadata + +.. _get_unique_order_request: + +Request: +******** + +.. code-block:: javascript + + GET /v1/orders/{order_uuid} + Headers: + Accept: application/json + X-Auth-Token: {token} + +Parameters +********** + +None + +.. _get_unique_order_response: + +Response: +********* + +.. code-block:: javascript + + 200 Success + + { + "created": "2015-10-20T18:49:02", + "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/5443d349-fe0c-4bfd-bd9d-99c4a9770638", + "secret_ref": "http://localhost:9311/v1/secrets/16f8d4f3-d3dd-4160-a5bd-8e5095a42613", + "status": "ACTIVE", + "sub_status": "Unknown", + "sub_status_message": "Unknown", + "type": "key", + "updated": "2015-10-20T18:49:02" + } + +.. _get_unique_order_response_attributes: + +Response Attributes +******************* + + ++--------------------+---------+----------------------------------------------------+ +| Name | Type | Description | ++====================+=========+====================================================+ +| created | string | Timestamp in ISO8601 format of when the order was | +| | | created | ++--------------------+---------+----------------------------------------------------+ +| creator_id | string | Keystone Id of the user who created the order | ++--------------------+---------+----------------------------------------------------+ +| meta | dict | Secret metadata used for informational purposes | ++--------------------+---------+----------------------------------------------------+ +| order_ref | string | Order href associated with the order | ++--------------------+---------+----------------------------------------------------+ +| secret_ref | string | Secret href associated with the order | ++--------------------+---------+----------------------------------------------------+ +| status | string | Current status of the order | ++--------------------+---------+----------------------------------------------------+ +| sub_status | string | Metadata associated with the order | ++--------------------+---------+----------------------------------------------------+ +| sub_status_message | string | Metadata associated with the order | ++--------------------+---------+----------------------------------------------------+ +| type | string | Indicates the type of order | ++--------------------+---------+----------------------------------------------------+ +| updated | string | Timestamp in ISO8601 format of the last time the | +| | | order was updated. | ++--------------------+---------+----------------------------------------------------+ + +.. _get_unique_orders_status_codes: + +HTTP Status Codes +***************** + ++------+-----------------------------------------------------------------------------+ +| Code | Description | ++======+=============================================================================+ +| 200 | Successfully retrieved the order | ++------+-----------------------------------------------------------------------------+ +| 400 | Bad Request | ++------+-----------------------------------------------------------------------------+ +| 401 | Invalid X-Auth-Token or the token doesn't have permissions to this resource | ++------+-----------------------------------------------------------------------------+ +| 404 | Not Found | ++------+-----------------------------------------------------------------------------+ + +.. _delete_unique_order: + +DELETE /v1/orders/{uuid} +######################## +Delete an order + +.. _delete_order_request: + +Request: +******** + +.. code-block:: javascript + + DELETE /v1/orders/{order_uuid} + Headers: + X-Auth-Token: {token} + + +Parameters +********** + +None + +.. _delete_order_response: + +Response: +********* + +.. code-block:: javascript + + 204 Success + + +.. _delete_order_status_codes: + +HTTP Status Codes +***************** + ++------+-----------------------------------------------------------------------------+ +| Code | Description | ++======+=============================================================================+ +| 204 | Successfully deleted the order | ++------+-----------------------------------------------------------------------------+ +| 400 | Bad Request | ++------+-----------------------------------------------------------------------------+ +| 401 | Invalid X-Auth-Token or the token doesn't have permissions to this resource | ++------+-----------------------------------------------------------------------------+ +| 404 | Not Found | ++------+-----------------------------------------------------------------------------+ \ No newline at end of file diff --git a/doc/source/api/userguide/orders.rst b/doc/source/api/userguide/orders.rst new file mode 100644 index 000000000..68f479e02 --- /dev/null +++ b/doc/source/api/userguide/orders.rst @@ -0,0 +1,166 @@ +*********************** +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 certificates and +public/private key pairs. + +The orders resource supports the following types: + * symmetric keys + * asymmetric keys + * certificates + +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 :doc:`development guide `. + +For a more in depth explanation on how to order a certificate, reference +the :ref:`How to Order a Certificate ` documentation. + +.. _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 :doc:`Orders API <../reference/orders>` 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 `.) + +.. 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 `. +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 :ref:`here `. + +.. _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 :ref:`orders parameters ` section of +the :doc:`Orders API <../reference/orders>` 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. \ No newline at end of file