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
parent
83e7caa02c
commit
c6bc39a3a9
@ -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 |
|
||||
+--------------------+---------------------------------------+---------------------------------------+---------------------------------------+
|
||||
Loading…
Reference in New Issue
Block a user