Adds documentation for consumer resource
Adds both the userguide and reference for consumers resource. Currently only a register, delete and retrieve guide are needed. Change-Id: I538579e7f38a6633a0dcea11e3cac0466dd32f62
This commit is contained in:
Thomas Dinkjian
parent
354c1b2874
commit
875f55ec89
@ -16,6 +16,7 @@ User Guide
|
|||||||
./userguide/cas
|
./userguide/cas
|
||||||
./userguide/dogtag_setup
|
./userguide/dogtag_setup
|
||||||
./userguide/quotas
|
./userguide/quotas
|
||||||
|
./userguide/consumers
|
||||||
|
|
||||||
API Reference
|
API Reference
|
||||||
#############
|
#############
|
||||||
@ -29,3 +30,4 @@ API Reference
|
|||||||
./reference/certificates
|
./reference/certificates
|
||||||
./reference/cas
|
./reference/cas
|
||||||
./reference/quotas
|
./reference/quotas
|
||||||
|
./reference/consumers
|
||||||
|
|||||||
284
doc/source/api/reference/consumers.rst
Normal file
284
doc/source/api/reference/consumers.rst
Normal file
@ -0,0 +1,284 @@
|
|||||||
|
*************************
|
||||||
|
Consumers API - Reference
|
||||||
|
*************************
|
||||||
|
|
||||||
|
GET {container_ref}/consumers
|
||||||
|
#############################
|
||||||
|
Lists a container's consumers.
|
||||||
|
|
||||||
|
The list of consumers can be filtered by the parameters passed in via the URL.
|
||||||
|
|
||||||
|
.. _consumer_parameters:
|
||||||
|
|
||||||
|
Parameters
|
||||||
|
**********
|
||||||
|
|
||||||
|
+----------+---------+----------------------------------------------------------------+
|
||||||
|
| Name | Type | Description |
|
||||||
|
+==========+=========+================================================================+
|
||||||
|
| offset | integer | The starting index within the total list of the consumers that |
|
||||||
|
| | | you would like to retrieve. |
|
||||||
|
+----------+---------+----------------------------------------------------------------+
|
||||||
|
| limit | integer | The maximum number of records to return (up to 100). The |
|
||||||
|
| | | default limit is 10. |
|
||||||
|
+----------+---------+----------------------------------------------------------------+
|
||||||
|
|
||||||
|
|
||||||
|
Request:
|
||||||
|
********
|
||||||
|
|
||||||
|
.. code-block:: None
|
||||||
|
|
||||||
|
GET {container_ref}/consumers
|
||||||
|
Headers:
|
||||||
|
X-Project-Id: {project_id}
|
||||||
|
|
||||||
|
Response:
|
||||||
|
*********
|
||||||
|
|
||||||
|
.. code-block:: None
|
||||||
|
|
||||||
|
200 OK
|
||||||
|
|
||||||
|
{
|
||||||
|
"total": 3,
|
||||||
|
"consumers": [
|
||||||
|
{
|
||||||
|
"status": "ACTIVE",
|
||||||
|
"URL": "consumerurl",
|
||||||
|
"updated": "2015-10-15T21:06:33.123878",
|
||||||
|
"name": "consumername",
|
||||||
|
"created": "2015-10-15T21:06:33.123872"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"status": "ACTIVE",
|
||||||
|
"URL": "consumerURL2",
|
||||||
|
"updated": "2015-10-15T21:17:08.092416",
|
||||||
|
"name": "consumername2",
|
||||||
|
"created": "2015-10-15T21:17:08.092408"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"status": "ACTIVE",
|
||||||
|
"URL": "consumerURL3",
|
||||||
|
"updated": "2015-10-15T21:21:29.970370",
|
||||||
|
"name": "consumername3",
|
||||||
|
"created": "2015-10-15T21:21:29.970365"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
|
||||||
|
Request:
|
||||||
|
********
|
||||||
|
|
||||||
|
.. code-block:: None
|
||||||
|
|
||||||
|
GET {container_ref}/consumers?limit=1&offset=1
|
||||||
|
Headers:
|
||||||
|
X-Project-Id: {project_id}
|
||||||
|
|
||||||
|
.. code-block:: None
|
||||||
|
{
|
||||||
|
"total": 3,
|
||||||
|
"next": "http://localhost:9311/v1/consumers?limit=1&offset=2",
|
||||||
|
"consumers": [
|
||||||
|
{
|
||||||
|
"status": "ACTIVE",
|
||||||
|
"URL": "consumerURL2",
|
||||||
|
"updated": "2015-10-15T21:17:08.092416",
|
||||||
|
"name": "consumername2",
|
||||||
|
"created": "2015-10-15T21:17:08.092408"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"previous": "http://localhost:9311/v1/consumers?limit=1&offset=0"
|
||||||
|
}
|
||||||
|
|
||||||
|
.. _consumer_response_attributes:
|
||||||
|
|
||||||
|
Response Attributes
|
||||||
|
*******************
|
||||||
|
|
||||||
|
+----------+---------+---------------------------------------------------------------+
|
||||||
|
| Name | Type | Description |
|
||||||
|
+==========+=========+============================================================== +
|
||||||
|
| consumers| list | Contains a list of dictionaries filled with consumer metadata.|
|
||||||
|
+----------+---------+---------------------------------------------------------------+
|
||||||
|
| total | integer | The total number of consumers available to the user. |
|
||||||
|
+----------+---------+---------------------------------------------------------------+
|
||||||
|
| next | string | A HATEOAS url to retrieve the next set of consumers based on |
|
||||||
|
| | | the offset and limit parameters. This attribute is only |
|
||||||
|
| | | available when the total number of consumers is greater than |
|
||||||
|
| | | offset and limit parameter combined. |
|
||||||
|
+----------+---------+---------------------------------------------------------------+
|
||||||
|
| previous | string | A HATEOAS url to retrieve the previous set of consumers based |
|
||||||
|
| | | on the offset and limit parameters. This attribute is only |
|
||||||
|
| | | available when the request offset is greater than 0. |
|
||||||
|
+----------+---------+---------------------------------------------------------------+
|
||||||
|
|
||||||
|
|
||||||
|
.. _consumer_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_consumers:
|
||||||
|
|
||||||
|
POST {container_ref}/consumers
|
||||||
|
##############################
|
||||||
|
|
||||||
|
Creates a consumer
|
||||||
|
|
||||||
|
Attributes
|
||||||
|
**********
|
||||||
|
|
||||||
|
+----------------------------+---------+----------------------------------------------+------------+
|
||||||
|
| Attribute Name | Type | Description | Default |
|
||||||
|
+============================+=========+==============================================+============+
|
||||||
|
| name | string | The name of the consumer set by the user. | None |
|
||||||
|
+----------------------------+---------+----------------------------------------------+------------+
|
||||||
|
| url | string | The url for the user or service using the | None |
|
||||||
|
| | | container. | |
|
||||||
|
+----------------------------+---------+----------------------------------------------+------------+
|
||||||
|
|
||||||
|
Request:
|
||||||
|
********
|
||||||
|
|
||||||
|
.. code-block:: None
|
||||||
|
|
||||||
|
POST {container_ref}/consumers
|
||||||
|
Headers:
|
||||||
|
X-Project-Id: {project_id}
|
||||||
|
|
||||||
|
Content:
|
||||||
|
{
|
||||||
|
"name": "ConsumerName",
|
||||||
|
"url": "ConsumerURL"
|
||||||
|
}
|
||||||
|
|
||||||
|
Response:
|
||||||
|
*********
|
||||||
|
|
||||||
|
.. code-block:: None
|
||||||
|
|
||||||
|
200 OK
|
||||||
|
|
||||||
|
{
|
||||||
|
"status": "ACTIVE",
|
||||||
|
"updated": "2015-10-15T17:56:18.626724",
|
||||||
|
"name": "container name",
|
||||||
|
"consumers": [
|
||||||
|
{
|
||||||
|
"URL": "consumerURL",
|
||||||
|
"name": "consumername"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"created": "2015-10-15T17:55:44.380002",
|
||||||
|
"container_ref": "http://localhost:9311/v1/containers/74bbd3fd-9ba8-42ee-b87e-2eecf10e47b9",
|
||||||
|
"creator_id": "b17c815d80f946ea8505c34347a2aeba",
|
||||||
|
"secret_refs": [
|
||||||
|
{
|
||||||
|
"secret_ref": "http://localhost:9311/v1/secrets/b61613fc-be53-4696-ac01-c3a789e87973",
|
||||||
|
"name": "private_key"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"type": "generic"
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
HTTP Status Codes
|
||||||
|
*****************
|
||||||
|
|
||||||
|
+------+-----------------------------------------------------------------------------+
|
||||||
|
| Code | Description |
|
||||||
|
+======+=============================================================================+
|
||||||
|
| 200 | OK |
|
||||||
|
+------+-----------------------------------------------------------------------------+
|
||||||
|
| 400 | Bad Request |
|
||||||
|
+------+-----------------------------------------------------------------------------+
|
||||||
|
| 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 consumer. This can be based on the the user's role or the |
|
||||||
|
| | project's quota. |
|
||||||
|
+------+-----------------------------------------------------------------------------+
|
||||||
|
|
||||||
|
|
||||||
|
.. _delete_consumer:
|
||||||
|
|
||||||
|
DELETE {container_ref}/consumers
|
||||||
|
################################
|
||||||
|
|
||||||
|
Delete a consumer.
|
||||||
|
|
||||||
|
Attributes
|
||||||
|
**********
|
||||||
|
|
||||||
|
+----------------------------+---------+----------------------------------------------+------------+
|
||||||
|
| Attribute Name | Type | Description | Default |
|
||||||
|
+============================+=========+==============================================+============+
|
||||||
|
| name | string | The name of the consumer set by the user. | None |
|
||||||
|
+----------------------------+---------+----------------------------------------------+------------+
|
||||||
|
| URL | string | The url for the user or service using the | None |
|
||||||
|
| | | container. | |
|
||||||
|
+----------------------------+---------+----------------------------------------------+------------+
|
||||||
|
|
||||||
|
Request:
|
||||||
|
********
|
||||||
|
|
||||||
|
.. code-block:: None
|
||||||
|
|
||||||
|
POST {container_ref}/consumers
|
||||||
|
Headers:
|
||||||
|
X-Project-Id: {project_id}
|
||||||
|
|
||||||
|
Content:
|
||||||
|
{
|
||||||
|
"name": "ConsumerName",
|
||||||
|
"URL": "ConsumerURL"
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
Response:
|
||||||
|
*********
|
||||||
|
|
||||||
|
.. code-block:: None
|
||||||
|
200 OK
|
||||||
|
|
||||||
|
{
|
||||||
|
"status": "ACTIVE",
|
||||||
|
"updated": "2015-10-15T17:56:18.626724",
|
||||||
|
"name": "container name",
|
||||||
|
"consumers": [],
|
||||||
|
"created": "2015-10-15T17:55:44.380002",
|
||||||
|
"container_ref": "http://localhost:9311/v1/containers/74bbd3fd-9ba8-42ee-b87e-2eecf10e47b9",
|
||||||
|
"creator_id": "b17c815d80f946ea8505c34347a2aeba",
|
||||||
|
"secret_refs": [
|
||||||
|
{
|
||||||
|
"secret_ref": "http://localhost:9311/v1/secrets/b61613fc-be53-4696-ac01-c3a789e87973",
|
||||||
|
"name": "private_key"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"type": "generic"
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
HTTP Status Codes
|
||||||
|
*****************
|
||||||
|
|
||||||
|
+------+-----------------------------------------------------------------------------+
|
||||||
|
| Code | Description |
|
||||||
|
+======+=============================================================================+
|
||||||
|
| 200 | OK |
|
||||||
|
+------+-----------------------------------------------------------------------------+
|
||||||
|
| 401 | Invalid X-Auth-Token or the token doesn't have permissions to this resource |
|
||||||
|
+------+-----------------------------------------------------------------------------+
|
||||||
|
| 404 | Not Found |
|
||||||
|
+------+-----------------------------------------------------------------------------+
|
||||||
153
doc/source/api/userguide/consumers.rst
Normal file
153
doc/source/api/userguide/consumers.rst
Normal file
@ -0,0 +1,153 @@
|
|||||||
|
*************************
|
||||||
|
Consumers API - User Guide
|
||||||
|
*************************
|
||||||
|
|
||||||
|
This guide assumes you will be using a local development environment of Barbican.
|
||||||
|
If you need assistance with getting set up, please reference the :doc:`development guide </setup/dev>`.
|
||||||
|
|
||||||
|
|
||||||
|
What is a Consumer?
|
||||||
|
###################
|
||||||
|
|
||||||
|
A consumer is a way to to register as an interested party for a container. All of the registered
|
||||||
|
consumers can be viewed by performing a GET on the {container_ref}/consumers. The idea
|
||||||
|
being that before a container is deleted all consumers should be notified of the delete.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
.. _create_consumer:
|
||||||
|
|
||||||
|
How to Create a Consumer
|
||||||
|
########################
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
curl -X POST -H 'X-Project-Id:12345' -H 'Content-Type: application/json' \
|
||||||
|
-d '{"name": "consumername", "URL": "consumerURL"}' \
|
||||||
|
http://localhost:9311/v1/containers/74bbd3fd-9ba8-42ee-b87e-2eecf10e47b9/consumers
|
||||||
|
|
||||||
|
This will return the following response:
|
||||||
|
|
||||||
|
.. code-block:: json
|
||||||
|
|
||||||
|
{
|
||||||
|
"status": "ACTIVE",
|
||||||
|
"updated": "2015-10-15T21:06:33.121113",
|
||||||
|
"name": "container name",
|
||||||
|
"consumers": [
|
||||||
|
{
|
||||||
|
"URL": "consumerurl",
|
||||||
|
"name": "consumername"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"created": "2015-10-15T17:55:44.380002",
|
||||||
|
"container_ref":
|
||||||
|
"http://localhost:9311/v1/containers/74bbd3fd-9ba8-42ee-b87e-2eecf10e47b9",
|
||||||
|
"creator_id": "b17c815d80f946ea8505c34347a2aeba",
|
||||||
|
"secret_refs": [
|
||||||
|
{
|
||||||
|
"secret_ref": "http://localhost:9311/v1/secrets/b61613fc-be53-4696-ac01-c3a789e87973",
|
||||||
|
"name": "private_key"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"type": "generic"
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
.. _retrieve_consumer:
|
||||||
|
|
||||||
|
How to Retrieve a Consumer
|
||||||
|
##########################
|
||||||
|
|
||||||
|
To retrieve a consumer perform a GET on the {container_ref}/consumers
|
||||||
|
This will return all consumers for this container. You can optionally add a
|
||||||
|
limit and offset query parameter.
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
curl -H 'X-Project-Id:12345' \
|
||||||
|
http://192.168.99.100:9311/v1/containers/74bbd3fd-9ba8-42ee-b87e-2eecf10e47b9/consumers
|
||||||
|
|
||||||
|
This will return the following response:
|
||||||
|
|
||||||
|
.. code-block:: json
|
||||||
|
|
||||||
|
{
|
||||||
|
"total": 1,
|
||||||
|
"consumers": [
|
||||||
|
{
|
||||||
|
"status": "ACTIVE",
|
||||||
|
"URL": "consumerurl",
|
||||||
|
"updated": "2015-10-15T21:06:33.123878",
|
||||||
|
"name": "consumername",
|
||||||
|
"created": "2015-10-15T21:06:33.123872"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
|
||||||
|
The returned value is a list of all consumers for the specified container.
|
||||||
|
Each consumer will be listed with its metadata..
|
||||||
|
|
||||||
|
If the offset and limit parameters are specified then you will see a
|
||||||
|
previous and next reference which allow you to cycle through all of
|
||||||
|
the consumers for this container.
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
curl -H 'X-Project-Id:12345' \
|
||||||
|
http://192.168.99.100:9311/v1/containers/74bbd3fd-9ba8-42ee-b87e-2eecf10e47b9/consumers?limit=1\&offset=1
|
||||||
|
|
||||||
|
This will return the following response:
|
||||||
|
|
||||||
|
.. code-block:: json
|
||||||
|
{
|
||||||
|
"total": 3,
|
||||||
|
"next": "http://localhost:9311/v1/consumers?limit=1&offset=2",
|
||||||
|
"consumers": [
|
||||||
|
{
|
||||||
|
"status": "ACTIVE",
|
||||||
|
"URL": "consumerURL2",
|
||||||
|
"updated": "2015-10-15T21:17:08.092416",
|
||||||
|
"name": "consumername2",
|
||||||
|
"created": "2015-10-15T21:17:08.092408"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"previous": "http://localhost:9311/v1/consumers?limit=1&offset=0"
|
||||||
|
}
|
||||||
|
|
||||||
|
.. _delete_consumer:
|
||||||
|
|
||||||
|
How to Delete a Consumer
|
||||||
|
########################
|
||||||
|
|
||||||
|
To delete a consumer for a container you must provide the consumer name and
|
||||||
|
URL which were used when the consumer was created.
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
curl -X DELETE -H 'X-Project-Id:12345' -H 'Content-Type: application/json' \
|
||||||
|
-d '{"name": "consumername", "URL": "consumerURL"}' \
|
||||||
|
http://localhost:9311/v1/containers/74bbd3fd-9ba8-42ee-b87e-2eecf10e47b9/consumers
|
||||||
|
|
||||||
|
This will return the following response:
|
||||||
|
|
||||||
|
.. code-block:: json
|
||||||
|
{
|
||||||
|
"status": "ACTIVE",
|
||||||
|
"updated": "2015-10-15T17:56:18.626724",
|
||||||
|
"name": "container name",
|
||||||
|
"consumers": [],
|
||||||
|
"created": "2015-10-15T17:55:44.380002",
|
||||||
|
"container_ref": "http://localhost:9311/v1/containers/74bbd3fd-9ba8-42ee-b87e-2eecf10e47b9",
|
||||||
|
"creator_id": "b17c815d80f946ea8505c34347a2aeba",
|
||||||
|
"secret_refs": [
|
||||||
|
{
|
||||||
|
"secret_ref": "http://localhost:9311/v1/secrets/b61613fc-be53-4696-ac01-c3a789e87973",
|
||||||
|
"name": "private_key"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"type": "generic"
|
||||||
|
}
|
||||||
|
|
||||||
|
A successful delete will return an HTTP 200 OK. The response content will be the
|
||||||
|
container plus the consumer list, minus the consumer which was just deleted.
|
||||||
Loading…
Reference in New Issue
Block a user