diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst index c371f4770..2affb66c6 100644 --- a/doc/source/api/index.rst +++ b/doc/source/api/index.rst @@ -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 diff --git a/doc/source/api/reference/consumers.rst b/doc/source/api/reference/consumers.rst new file mode 100644 index 000000000..9f9617733 --- /dev/null +++ b/doc/source/api/reference/consumers.rst @@ -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 | ++------+-----------------------------------------------------------------------------+ diff --git a/doc/source/api/userguide/consumers.rst b/doc/source/api/userguide/consumers.rst new file mode 100644 index 000000000..65b239007 --- /dev/null +++ b/doc/source/api/userguide/consumers.rst @@ -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 `. + + +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. \ No newline at end of file