openstack/barbican
Code Issues Proposed changes

Merge "Starting to rework docs around the secret resource"

Browse Source
This commit is contained in:
Jenkins
2015-03-20 19:58:44 +00:00
committed by Gerrit Code Review
parent 6c0777b5a7 3c935a82d1
commit f9a00d76ad
3 changed files with 192 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
doc/source/api/index.rst Normal file
View File

@@ -0,0 +1,21 @@
**************************
Barbican API Documentation
**************************
Quick Start
###########
.. toctree::
:maxdepth: 1
./quickstart/secrets
API Reference
#############
.. toctree::
:maxdepth: 1
./reference/secrets

34
doc/source/api/quickstart/secrets.rst Normal file
View File

@@ -0,0 +1,34 @@
*************************
Secrets API - Quick Start
*************************
The secrets resource is the heart of the Barbican service. It provides access
to the secret / keying material stored in the system.
Barbican supports the storage of data for various content-types securely.
TODO(jvrbanac): Add more information about the secrets resource
What is a secret
################
TODO(jvrbanac): Add a summary here
How to create a secret
######################
TODO(jvrbanac): Add examples
How to update a secret
######################
TODO(jvrbanac): Add examples
How to retrieve a secret
########################
TODO(jvrbanac): Add examples
How to delete a secret
######################
TODO(jvrbanac): Add examples

137
doc/source/api/reference/secrets.rst Normal file
View File

@@ -0,0 +1,137 @@
***********************
Secrets API - Reference
***********************
GET /secrets
############
Lists a project's secrets.
The list of secrets can be filtered by the parameters passed in via the URL.
Parameters
**********
+--------+---------+----------------------------------------------------------------+
| Name | Type | Description |
+========+=========+================================================================+
| offset | integer | The starting index within the total list of the secrets that |
| | | you would like to retrieve. |
+--------+---------+----------------------------------------------------------------+
| limit | integer | The maximum number of records to return (up to 100). The |
| | | default limit is 10. |
+--------+---------+----------------------------------------------------------------+
| name | string | Selects all secrets with name equal to this value. |
+--------+---------+----------------------------------------------------------------+
| bits | integer | Selects all secrets with bit_length equal to this value. |
+--------+---------+----------------------------------------------------------------+
| alg | string | Selects all secrets with algorithm equal to this value. |
+--------+---------+----------------------------------------------------------------+
| mode | string | Selects all secrets with mode equal to this value. |
+--------+---------+----------------------------------------------------------------+
Response Attributes
*******************
+----------+---------+--------------------------------------------------------------+
| Name | Type | Description |
+==========+=========+==============================================================+
| secrets | list | Contains a list of dictionaries filled with secret metadata. |
+----------+---------+--------------------------------------------------------------+
| total | integer | The total number of secrets available to the user. |
+----------+---------+--------------------------------------------------------------+
| next | string | A HATEOS url to retrieve the next set of secrets based on |
| | | the offset and limit parameters. This attribute is only |
| | | available when the total number of secrets is greater than |
| | | offset and limit parameter combined. |
+----------+---------+--------------------------------------------------------------+
| previous | string | A HATEOS url to retrieve the previous set of secrets based |
| | | on the offset and limit parameters. This attribute is only |
| | | available when the request offset is greater than 0. |
+----------+---------+--------------------------------------------------------------+
HTTP Status Codes
*****************
+------+-----------------------------------------------------------------------------+
| Code | Description |
+======+=============================================================================+
| 200 | Successful Request |
+------+-----------------------------------------------------------------------------+
| 401 | Invalid X-Auth-Token or the token doesn't have permissions to this resource |
+------+-----------------------------------------------------------------------------+
POST /secrets
#############
Creates a secret
Attributes
**********
+----------------------------+---------+----------------------------------------------+------------+
| Attribute Name | Type | Description | Default |
+============================+=========+==============================================+============+
| name | string | (optional) The name of the secret set by the | None |
| | | user. | |
+----------------------------+---------+----------------------------------------------+------------+
| expiration | string | (optional) This is a timestamp in ISO 8601 | None |
| | | format ``YYYY-MM-DDTHH:MM:SSZ.`` | |
+----------------------------+---------+----------------------------------------------+------------+
| algorithm | string | (optional) Metadata provided by a user or | None |
| | | system for informational purposes. | |
+----------------------------+---------+----------------------------------------------+------------+
| bit_length | integer | (optional) Metadata provided by a user or | None |
| | | system for informational purposes. | |
+----------------------------+---------+----------------------------------------------+------------+
| mode | string | (optional) Metadata provided by a user or | None |
| | | system for informational purposes. | |
+----------------------------+---------+----------------------------------------------+------------+
| payload | string | (optional) The secret's data to be stored. | None |
| | | ``payload_content_type`` must also be | |
| | | supplied if payload is provided. | |
+----------------------------+---------+----------------------------------------------+------------+
| payload_content_type | string | (optional) (required if payload is added) | None |
| | | The type and format of the secret data. The | |
| | | two supported types are ``text/plain`` and | |
| | | ``application/octet-stream``. | |
+----------------------------+---------+----------------------------------------------+------------+
| payload_content_encoding | string | (optional) The encoding used to format the | None |
| | | payload provided. Currently only base64 is | |
| | | supported. This is required if content type | |
| | | provided has an encoding available. | |
+----------------------------+---------+----------------------------------------------+------------+
| secret_type | string | (optional) Used to indicate the type of | ``opaque`` |
| | | secret being stored. If no value is given, | |
| | | ``opaque`` is used as the default, which is | |
| | | used to signal Barbican to just store the | |
| | | information without worrying about format or | |
| | | encoding. | |
+----------------------------+---------+----------------------------------------------+------------+
TODO(jvrbanac): Finish this section
GET /secrets/{uuid}
###################
Retrieves a secret's metadata by uuid
TODO(jvrbanac): Finish this section
DELETE /secrets/{uuid}
######################
Delete a secret by uuid
TODO(jvrbanac): Finish this section
GET /secrets/{uuid}/payload
###########################
Retrieve a secret's payload
TODO(jvrbanac): Finish this section
PUT /secrets/{uuid}/payload
###########################
Update a secret's payload
TODO(jvrbanac): Finish this section