Create Orders Documentation
Creates the orders reference API and user guide. Also updated the index page for the api to include the reference to the orders docs. Change-Id: Ib409683b9f5c93d3e58f476d012f8e069e0ca886
This commit is contained in:
Chris Solis
parent
8b930cff24
commit
25cd31e03e
@ -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
|
||||
|
||||
364
doc/source/api/reference/orders.rst
Normal file
364
doc/source/api/reference/orders.rst
Normal file
@ -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 |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
166
doc/source/api/userguide/orders.rst
Normal file
166
doc/source/api/userguide/orders.rst
Normal file
@ -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 </setup/dev>`.
|
||||
|
||||
For a more in depth explanation on how to order a certificate, reference
|
||||
the :ref:`How to Order a Certificate <order_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 <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 :ref:`here <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 :ref:`orders parameters <get_order_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.
|
||||
Loading…
x
Reference in New Issue
Block a user