openstack
/
barbican
Code Issues Proposed changes

Removing orphan and deprecated doc page: api.rst 

Change-Id: I35aee4890937bd427b94c9637045628dd5a032f4
Signed-off-by: Carlos Marin <ing.cma@gmail.com>
This commit is contained in:
Carlos Marin 2016-02-26 14:25:16 -06:00
parent 83e7caa02c
commit c6bc39a3a9
1 changed files with 0 additions and 439 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

439
doc/source/api.rst
View File

@ -1,439 +0,0 @@
=================================
Application Programming Interface
=================================
THESE DOCS ARE DEPRECATED AS OF APR 2015
########################################
This wiki page details the API for the latest Barbican release. In particular:
* `Endpoints & Versioning`_ - Brief discussion about Barbican's approach to
service URIs.
* `Secrets Resource`_ - Details storing, retrieving and deleting secrets.
* `Orders Resource`_ - Details the ordering facilities for Barbican, used
to generate secrets asynchronously.
* `Containers Resource`_ - Details storing, retrieving and deleting
containers.
* `Consumers Resource`_ - Details adding, removing and listing consumers
associated with container instances.
* `Examples`_ - Provides specific examples utilizing the secrets and
orders API.
Endpoints & Versioning
======================
The barbican service is assumed to be hosted on an SSL enabled, geographically
labelled endpoint. An example for a valid URI might look like the following:
https://dfw.secrets.api.rackspacecloud.com
Versioning will be achieved through a URI constant element, as shown in the
example below:
https://dfw.secrets.api.rackspacecloud.com/v1/
Regarding Role Based Access Control (RBAC) of Resources
=======================================================
Resource access in Barbican is subject to RBAC constraints, as detailed in
`this link`_.
RBAC failures will result in a 403 Forbidden response.
.. _`this link`: https://github.com/cloudkeep/barbican/wiki/Role-Based-Access-Control
Secrets Resource
================
Secrets Resource Moved to :doc:`Secrets Reference <api/reference/secrets>`
Orders Resource
===============
The ordering resource allows for the generation of secret material by Barbican.
The ordering object encapsulates the workflow and history for the creation of a
secret. This interface is implemented as an asynchronous process since the time
to generate a secret can vary depending on the type of secret.
POST
----
An example of an `orders` POST request is below.
.. code-block:: javascript
POST v1/orders
Header: content-type=application/json
X-Project-Id: {project_id}
{
"type": "key",
"meta": {
"name": "secretname",
"algorithm": "AES",
"bit_length": 256,
"mode": "cbc",
"payload_content_type": "application/octet-stream"
}
}
Where the elements of the `meta` element match those of the `secret` POST
request above, but without the `payload` attributes. _Note however that unlike
with the `secrets` resource, the `algorithm`, `bit_length` and `mode`
attributes are validated, to ensure that a secret can be generated per these
specifications._ The `type` parameter selects the secret to generate: `key`
generates a symmetric key; `asymmetric` generates a public/private PKI key pair
(in a Container object); certificate` generates an SSL certificate (not
currently operational).
If the Content-Type in the HTTP header is not set to "application/json" then
the POST call will fail with an HTTP 415 error.
PUT
---
Currently nothing can be edited in an order.
GET - Individual Order
----------------------
GET requests for an `order` will return a response such as in the example
below.
.. code-block:: javascript
GET v1/orders/{order_id}
Headers: X-Project-Id: {project_id}
{
"type": "key",
"meta": {
"name": "secretname",
"algorithm": "aes",
"bit_length": 256,
"mode": "cbc",
"payload_content_type": "application/octet-stream"
},
"order_ref": "http://localhost:8080/v1/orders/f9b633d8-fda5-4be8-b42c-5b2c9280289e",
"secret_ref": "http://localhost:8080/v1/secrets/888b29a4-c7cf-49d0-bfdf-bd9e6f26d718",
"status": "ERROR",
"error_status_code": "400 Bad Request",
"error_reason": "Secret creation issue seen - content-encoding of 'bogus' not supported."
}
Where:
* **meta** - Secret parameters provided in the original order request. _Note
that this is not the same as retrieving a Secret resource per the `secrets`
resource, so elements such as a secret's `content_types` will not be
displayed. To see such details, perform a GET on the `secret_ref`._
* **type** - Secret type in the original order request.
* **order_ref** - URI to this order.
* **status** - Status of the order, one of PENDING, ACTIVE or ERROR. Clients
should poll the order for a status change to ACTIVE (in which case
`secret_ref` has the secret details) or ERROR (in which case `error_reason`
has the error reason, and 'error_status_code' has an HTTP-style status code).
* **secret_ref** - URI to the secret *once it is generated*. This field is not
available unless the status is ACTIVE.
* **error_status_code** - (optional) HTTP-style status code of the root cause
error condition, only if status is ERROR.
* **error_reason** - (optional) Details of the root cause error condition, only
if status is ERROR.
GET - List of Orders Per Project
--------------------------------
Performing a GET on the orders resource with no UUID retrieves a batch of the
most recent orders per the requesting project, as per the example response
below. The `limit` and `offset` parameters function similar to the GET secrets
list detailed above.
.. code-block:: javascript
GET http://localhost:9311/v1/orders?limit=3&offset=2
Headers: X-Project-Id: {project_id}
{
"orders": [
{
"status": "ACTIVE",
"secret_ref": "http://localhost:9311/v1/secrets/bf2b33d5-5347-4afb-9009-b4597f415b7f",
"updated": "2013-06-28T18:29:37.058718",
"created": "2013-06-28T18:29:36.001750",
"type": "key",
"meta": {
"name": "secretname",
"algorithm": "aes",
"bit_length": 256,
"mode": "cbc",
"payload_content_type": "application/octet-stream"
},
"order_ref": "http://localhost:9311/v1/orders/3100078a-6ab1-4c3f-ab9f-295938c91733"
},
{
"status": "ACTIVE",
"secret_ref": "http://localhost:9311/v1/secrets/fa71b143-f10e-4f7a-aa82-cc292dc33eb5",
"updated": "2013-06-28T18:29:37.058718",
"created": "2013-06-28T18:29:36.001750",
"type": "key",
"meta": {
"name": "secretname",
"algorithm": "aes",
"bit_length": 256,
"mode": "cbc",
"payload_content_type": "application/octet-stream"
},
"order_ref": "http://localhost:9311/v1/orders/30b3758a-7b8e-4f2c-b9f0-f590c6f8cc6d"
}
]
}
The retrieved list of orders is ordered by oldest to newest `created` date.
Orders Summary
--------------
> https://.../v1/orders/
+--------+-------------------------------------------------------------------+
| Method | Description |
+========+===================================================================+
| GET | Returns a list of all orders for a customer. |
+--------+-------------------------------------------------------------------+
| POST | Starts the process of creating a secret. This call will return |
| | immediately with a 202 OK and a link to the detail order object |
| | (see below). |
+--------+-------------------------------------------------------------------+
> https://.../v1/orders/{order_uuid}
+--------+-------------------------------------------------------------------+
| Method | Description |
+========+===================================================================+
| GET | Returns the detailed order data including a link to the secret |
| | generated as a result of the order (if available). |
+--------+-------------------------------------------------------------------+
| PUT | **Not yet supported**. Allows the editing of an order where |
| | allowed. |
+--------+-------------------------------------------------------------------+
| DELETE | Cancels an order. |
+--------+-------------------------------------------------------------------+
Error Responses
~~~~~~~~~~~~~~~
+------------------------+-------+-------------------------------------------+
| Action | Error | Notes |
| | Code | |
+========================+=======+===========================================+
| POST order with | 400 | Can include schema violations such as the |
| invalid data | | secret's mime-type not specified |
+------------------------+-------+-------------------------------------------+
| POST order with | 415 | Caused when the API doesn't support the |
| 'Content-Type' header | | specified Content-Type header |
| not supported | | |
+------------------------+-------+-------------------------------------------+
| POST secret with | 400 | Caused when no crypto plugin supports the |
| 'payload_content_type' | | payload_content_type requested |
| not supported | | |
+------------------------+-------+-------------------------------------------+
| GET order that doesn't | 404 | The supplied UUID doesn't match a order |
| exist | | in the data store |
+------------------------+-------+-------------------------------------------+
| DELETE order that | 404 | The supplied UUID doesn't match a order |
| doesn't exist | | in the data store |
+------------------------+-------+-------------------------------------------+
Containers Resource
===================
Containers Resource Moved to :doc:`Containers Reference <api/reference/containers>`
Consumers Resource
==================
The consumers resource allows clients to register as interested in specific
container instances (as created per the previous section). Clients can then
query containers for the consumers that registered interest in them. Client
workflows could use this list (for example) to warn of attempts to remove
containers that have registered consumers. Note that Barbican allows containers
to be deleted even if there are registered consumers for them.
POST
----
An example of an `consumers` POST request is below.
.. code-block:: javascript
POST v1/containers/888b29a4-c7cf-49d0-bfdf-bd9e6f26d718/consumers
Header: content-type=application/json
X-Project-Id: {project_id}
{
"name": "foo-service",
"URL": "https://www.fooservice.com/widgets/1234"
}
Where the `name` is typically the name of the remote service registering as a
consumer for this container instance, and 'URL' is typically a URL to a
resource in the remote service that utilizes the container's secrets somehow,
such as a load balancer that has a container's SSL certificate installed onto
it.
Note that subsequent POSTs to the same container instance with the same `name`
attribute will replace the previous URL registered for that `name`.
GET - List of Consumers Per Container Instance
----------------------------------------------
**Note: This feature seems to be broken currently, by not displaying the
navigation links per the example below.**
Performing a GET on a specific container resource returns a list of consumers
that registered with it. The `limit` and `offset` parameters function similar
to the GET secrets list detailed above.
.. code-block:: javascript
GET http://localhost:9311/v1/containers/888b29a4-c7cf-49d0-bfdf-bd9e6f26d718/consumers?limit=3&offset=2
Headers: X-Project-Id: {project_id}
{
"consumers": [
{
"name": "foo-service",
"URL": "https://www.fooservice.com/widgets/1234"
},
{
"name": "barService",
"URL": "https://www.barservice.com/mythings/5678"
}
],
"next":"http://localhost:9311/v1/containers/888b29a4-c7cf-49d0-bfdf-bd9e6f26d718/consumers?limit=10&offset=10"
}
The retrieved list of consumers is ordered by oldest to newest `created` date.
Consumers Summary
-----------------
> https://.../v1/containers/<container-UUID>/consumers
+--------+-------------------------------------------------------------------+
| Method | Description |
+========+===================================================================+
| GET | Returns a list of all consumers registered for a container. |
+--------+-------------------------------------------------------------------+
| POST | Registers/adds consumer information to a container. |
+--------+-------------------------------------------------------------------+
| DELETE | Removes a registered consumer by specifying its `name` and `URL` |
| | in the JSON payload. |
+--------+-------------------------------------------------------------------+
Examples
========
The following are example combinations, inspired by `this page`_.
.. _`this page`: http://stackoverflow.com/questions/11946920/http-content-negotiation-compression-use-base64-with-accept-encoding-content-en
The tables in this section are focused on the content-types and
content-encodings of the various REST verb flows, even though each flow might
have a different way to specify these values (either via http header settings
or JSON request field). The reason for this approach is that while each flow
has a different means to specify the mime-type and encoding, the values set for
them must still be consistent with valid mime-type or encoding selections.
One-Step UTF-8/ASCII Secret Create/Retrieve
-------------------------------------------
+--------------------+---------------------------------------+-----------------------------+---------------------------------+
| Action | content-type | content-encoding | Result |
+====================+=======================================+=============================+=================================+
| POST secrets | `payload_content_type` = `text/plain` | `payload_content_encoding` | Supplied `payload` is encrypted |
| | | Not required/ignored | |
+--------------------+---------------------------------------+-----------------------------+---------------------------------+
| GET secrets (meta) | `Accept: application/json` | Not required/ignored | JSON metadata, with |
| | | | `Content-Types` set to |
| | | | `'default':'text/plain'` |
+--------------------+---------------------------------------+-----------------------------+---------------------------------+
| GET secrets | `Accept: text/plain` | Not required/ignored | Previous `payload` is decrypted |
| | | | and returned |
+--------------------+---------------------------------------+-----------------------------+---------------------------------+
One-Step Binary Secret Create/Retrieve
--------------------------------------
+--------------------+---------------------------------------+---------------------------------------+----------------------------------------+
| Action | content-type | content-encoding | Result |
+====================+=======================================+=======================================+========================================+
| POST secrets | `payload_content_type` = | `payload_content_encoding` = `base64` | Supplied `payload` is converted from |
| | `application/octet-stream` | | base64 to binary, then encrypted. |
+--------------------+---------------------------------------+---------------------------------------+----------------------------------------+
| GET secrets (meta) | `Accept: application/json` | Not required/ignored | JSON metadata, with `Content-Types` |
| | | | set to |
| | | | `'default':'application/octet-stream'` |
+--------------------+---------------------------------------+---------------------------------------+----------------------------------------+
| GET secrets | `Accept: application/octet-stream` | Not specified | Previous `payload` is decrypted and |
| (decrypted) | | | returned as raw binary, *even if the |
| | | | POST provided the data in `base64`*. |
+--------------------+---------------------------------------+---------------------------------------+----------------------------------------+
Two-Step Binary Secret Create/Retrieve
--------------------------------------
+--------------------+------------------------------------------+---------------------------------------+---------------------------------------+
| Action | content-type | content-encoding | Result |
+====================+==========================================+=======================================+=======================================+
| POST secrets | `payload_content_type` | `payload_content_encoding` Not | Only metadata is created. If the |
| | Not required/ignored | required/ignored | `payload_content_type` or |
| | | | `payload_content_encoding` fields |
| | | | were provided, they are not used or |
| | | | saved with the metadata. The PUT |
| | | | request (next) will determine the |
| | | | secret's content type |
+--------------------+------------------------------------------+---------------------------------------+---------------------------------------+
| PUT secrets | `Content-Type: application/octet-stream` | `Content-Encoding: base64` | Supplied request body is *converted |
| (option #1 - as | | | from base64 to binary*, then |
| base64) | | | encrypted |
+--------------------+------------------------------------------+---------------------------------------+---------------------------------------+
| PUT secrets | `Content-Type: application/octet-stream` | Not specified | Supplied request body is encrypted as |
| (option #2 - as | | | is |
| binary) | | | |
+--------------------+------------------------------------------+---------------------------------------+---------------------------------------+
| GET secrets (meta) | `Accept: application/json` | Not required/ignored | JSON metadata, with `Content-Types` |
| | | | set to |
| | | | `'default':'application/octet-stream'`|
+--------------------+------------------------------------------+---------------------------------------+---------------------------------------+
| GET secrets | `Accept: application/octet-stream` | Not specified | Previous request is decrypted and |
| (decrypted) | | | returned as raw binary, *even if the |
| | | | PUT provided the data in `base64`*. |
+--------------------+------------------------------------------+---------------------------------------+---------------------------------------+
Two-Step Plain-Text Secret Create/Retrieve
------------------------------------------
+--------------------+---------------------------------------+---------------------------------------+---------------------------------------+
| Action | content-type | content-encoding | Result |
+====================+=======================================+=======================================+=======================================+
| POST secrets | `payload_content_type` Not | `payload_content_encoding` Not | Only metadata is created. If the |
| | required/ignored | required/ignored | `payload_content_type` or |
| | | | `payload_content_encoding` fields |
| | | | were provided, they are not used or |
| | | | saved with the metadata. The PUT |
| | | | request (next) will determine the |
| | | | secret's content format |
+--------------------+---------------------------------------+---------------------------------------+---------------------------------------+
| PUT secrets | `Content-Type: text/plain` | Not required/ignored | Supplied request body is encrypted as |
| | | | is |
+--------------------+---------------------------------------+---------------------------------------+---------------------------------------+
| GET secrets (meta) | `Accept: application/json` | Not required/ignored | JSON metadata, with `Content-Types` |
| | | | set to `'default':'text/plain'` |
+--------------------+---------------------------------------+---------------------------------------+---------------------------------------+
| GET secrets | `Accept: text/plain` | Not specified | Previous request is decrypted and |
| (decrypted) | | | returned as utf-8 text |
+--------------------+---------------------------------------+---------------------------------------+---------------------------------------+