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/dogtag_setup
|
||||
./userguide/quotas
|
||||
./userguide/consumers
|
||||
|
||||
API Reference
|
||||
#############
|
||||
@ -29,3 +30,4 @@ API Reference
|
||||
./reference/certificates
|
||||
./reference/cas
|
||||
./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