* Docs: API overview text clarity & kv2 mention... #16746 Corrected text and terminology. Relates to #6378 & should allow for closure of that issue too. <img width="1158" alt="Screenshot 2022-08-16 at 19 23 20" src="https://user-images.githubusercontent.com/974854/184941452-2b2c680a-b6d5-4db6-85aa-e5dc672499f6.png"> * Trigger CI * Update website/content/api-docs/index.mdx Co-authored-by: Ben Ash <32777270+benashz@users.noreply.github.com> * Update website/content/api-docs/index.mdx Co-authored-by: Ben Ash <32777270+benashz@users.noreply.github.com> * Update website/content/api-docs/index.mdx Co-authored-by: Ben Ash <32777270+benashz@users.noreply.github.com> * Update website/content/api-docs/index.mdx Co-authored-by: Ben Ash <32777270+benashz@users.noreply.github.com> * Update website/content/api-docs/index.mdx Co-authored-by: Ben Ash <32777270+benashz@users.noreply.github.com> * Updated based on feedback. * Docs: API overview text clarity & kv2 mention... Added KV2 explict further to feedback from @benashz. Also: - Adjusted very first paragraph a bit. - improved grammer and over use of `via` and `to` in certian places. Co-authored-by: Zlaticanin <zlaticaninmilena@gmail.com> Co-authored-by: Ben Ash <32777270+benashz@users.noreply.github.com> Co-authored-by: Yoko Hyakuna <yoko@hashicorp.com>
This commit is contained in:
aphorise
GitHub
parent
d67023c3b3
commit
571cf3dc85
|
|
@ -6,9 +6,9 @@ description: Vault has an HTTP API that can be used to control every aspect of V
|
|||
|
||||
# HTTP API
|
||||
|
||||
The Vault HTTP API gives you full access to Vault via HTTP. Every aspect of
|
||||
Vault can be controlled via this API. The Vault CLI uses the HTTP API to access
|
||||
Vault.
|
||||
The Vault HTTP API gives you full access to Vault using [REST like HTTP verbs](https://en.wikipedia.org/wiki/Representational_state_transfer).
|
||||
Every aspect of Vault can be controlled using the APIs. The Vault CLI uses the
|
||||
HTTP API to access Vault similar to all other consumers.
|
||||
|
||||
All API routes are prefixed with `/v1/`.
|
||||
|
||||
|
|
@ -21,12 +21,6 @@ is, `sys/` routes) change very infrequently, but various secrets engines/auth
|
|||
methods/etc. sometimes have minor changes to accommodate new features as
|
||||
they're developed.
|
||||
|
||||
## KV Engine V2
|
||||
|
||||
For KV Engine V2, request path needs to include `/data`.
|
||||
Example:
|
||||
`http://127.0.0.1:8200/v1/secret/data/foo`
|
||||
|
||||
## Transport
|
||||
|
||||
The API is expected to be accessed over a TLS connection at all times, with a
|
||||
|
|
@ -41,8 +35,8 @@ A user may have a client token sent to them. The client token must be sent as
|
|||
either the `X-Vault-Token` HTTP Header or as `Authorization` HTTP Header using
|
||||
the `Bearer <token>` scheme.
|
||||
|
||||
Otherwise, a client token can be retrieved via [authentication
|
||||
backends](/docs/auth).
|
||||
Otherwise, a client token can be retrieved using an [authentication
|
||||
engine](/docs/auth).
|
||||
|
||||
Each auth method has one or more unauthenticated login endpoints. These
|
||||
endpoints can be reached without any authentication, and are used for
|
||||
|
|
@ -50,7 +44,7 @@ authentication to Vault itself. These endpoints are specific to each auth
|
|||
method.
|
||||
|
||||
Responses from auth login methods that generate an authentication token are
|
||||
sent back to the client via JSON. The resulting token should be saved on the
|
||||
sent back to the client in JSON. The resulting token should be saved on the
|
||||
client or passed via the `X-Vault-Token` or `Authorization` header for future requests.
|
||||
|
||||
## Parameter restrictions
|
||||
|
|
@ -60,16 +54,17 @@ in periods. Otherwise, Vault will return a 404 unsupported path error.
|
|||
|
||||
## Namespaces
|
||||
|
||||
If using the [Namespaces](/docs/enterprise/namespaces) feature, API
|
||||
operations are relative to the namespace value passed in via the
|
||||
`X-Vault-Namespace` header. For instance, if the request path is to
|
||||
`secret/foo`, and the header is set to `ns1/ns2/`, the final request path Vault
|
||||
uses will be `ns1/ns2/secret/foo`. Note that it is semantically equivalent to
|
||||
use a full path rather than the `X-Vault-Namespace` header, as the operation in
|
||||
Vault will always look up the correct namespace based on the final given path.
|
||||
Thus, it would be equivalent to the above example to set `X-Vault-Namespace` to
|
||||
`ns1/` and a request path of `ns2/secret/foo`, or to not set
|
||||
`X-Vault-Namespace` at all and use a request path of `ns1/ns2/secret/foo`.
|
||||
When using [Namespaces](/docs/enterprise/namespaces) the final path of the API
|
||||
request is relative to the `X-Vault-Namespace` header. For instance, if a
|
||||
request URI is `secret/foo` with the `X-Vault-Namespace` header set as `ns1/ns2/`,
|
||||
then the resulting request path to Vault will be `ns1/ns2/secret/foo`.
|
||||
|
||||
Note that it is semantically equivalent to use the full path rather than the
|
||||
`X-Vault-Namespace` header, Vault will match the corresponding namespace
|
||||
based on correlating user input. Similar path results may be achieved if
|
||||
`X-Vault-Namespace` is set to `ns1/` with the request path of `ns2/secret/foo`
|
||||
as well, or otherwise if `X-Vault-Namespace` is omitted entirely and instead a
|
||||
complete path is provided such as: `ns1/ns2/secret/foo`.
|
||||
|
||||
For example, the following two commands result in equivalent requests:
|
||||
|
||||
|
|
@ -90,16 +85,16 @@ $ curl \
|
|||
|
||||
## API Operations
|
||||
|
||||
With few documented exceptions, all request body data and response data from
|
||||
Vault is via JSON. Vault will set the `Content-Type` header appropriately but
|
||||
does not require that clients set it.
|
||||
Typically the request data, body and response data to and from Vault is in JSON.
|
||||
Vault sets the `Content-Type` header appropriately with its response and does
|
||||
not require it from the clients request.
|
||||
|
||||
Different plugins implement different APIs according to their functionality.
|
||||
The examples below are created with the `KVv1` backend, which acts like a very
|
||||
simple Key/Value store. Read the documentation for a particular backend for
|
||||
detailed information on its API; this simply provides a general overview.
|
||||
The demonstration below uses the [`KVv1` secrets engine](/api/secret/kv/kv-v1), which is a
|
||||
simple Key/Value store. Please read [the API documentation of KV secret engines](/api/secret/kv)
|
||||
for details of `KVv1` compared to `KVv2` and how they differ in their URI paths
|
||||
as well as the features available in version 2 of the KV secrets engine.
|
||||
|
||||
For `KVv1`, reading a secret via the HTTP API is done by issuing a GET:
|
||||
For `KVv1`, reading a secret using the HTTP API is done by issuing a GET:
|
||||
|
||||
```text
|
||||
/v1/secret/foo
|
||||
|
|
@ -117,15 +112,15 @@ $ curl \
|
|||
http://127.0.0.1:8200/v1/secret/foo
|
||||
```
|
||||
|
||||
A few endpoints consume query parameters via `GET` calls, but only if those
|
||||
parameters are not sensitive, as some load balancers will log these. Most
|
||||
endpoints that consume parameters use `POST` instead and put the parameters in
|
||||
the request body.
|
||||
A few endpoints consume calls with `GET` query string parameters, but only if
|
||||
those parameters are not sensitive, especially since some load balancers will
|
||||
be able log these. Most endpoints that accept `POST` query string parameters
|
||||
expect those parameters in the request body.
|
||||
|
||||
You can list secrets as well. To do this, either issue a GET with the query
|
||||
parameter `list=true`, or you can use the `LIST` HTTP verb. For the `kv`
|
||||
backend, listing is allowed on directories only, and returns the keys in the
|
||||
given directory:
|
||||
You can list secrets as well. To do this, either issue a `GET` with the query
|
||||
string parameter `list=true`, or you use the `LIST` HTTP verb. For the `kv` secrets
|
||||
engine, listing is allowed on directories only, which returns the keys at the
|
||||
requested path:
|
||||
|
||||
```shell-session
|
||||
$ curl \
|
||||
|
|
@ -137,7 +132,7 @@ $ curl \
|
|||
The API documentation uses `LIST` as the HTTP verb, but you can still use `GET`
|
||||
with the `?list=true` query string.
|
||||
|
||||
To use an API that consumes data via request body, issue a `POST`:
|
||||
To make an API with specific data in request body, issue a `POST`:
|
||||
|
||||
```text
|
||||
/v1/secret/foo
|
||||
|
|
@ -163,11 +158,23 @@ $ curl \
|
|||
```
|
||||
|
||||
Vault currently considers `PUT` and `POST` to be synonyms. Rather than trust a
|
||||
client's stated intentions, Vault backends can implement an existence check to
|
||||
client's stated intentions, Vault engines can implement an existence check to
|
||||
discover whether an operation is actually a create or update operation based on
|
||||
the data already stored within Vault. This makes permission management via ACLs
|
||||
more flexible.
|
||||
|
||||
A [KVv2 example](api/secret/kv/kv-v2#sample-request-3) for the engine path of `secret` requires that URI is
|
||||
appended with ***`data/`*** prior to the secret name (`baz`) such as:
|
||||
|
||||
```shell-session
|
||||
$ curl \
|
||||
-H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \
|
||||
-H "Content-Type: application/json" \
|
||||
-X POST \
|
||||
-d '{"data":{"value":"bar"}}' \
|
||||
http://127.0.0.1:8200/v1/secret/data/baz
|
||||
```
|
||||
|
||||
For more examples, please look at the Vault API client.
|
||||
|
||||
## The `X-Vault-Request` Header
|
||||
|
|
@ -192,12 +199,16 @@ addition, the Vault SDK always adds this header to every request.
|
|||
|
||||
## Help
|
||||
|
||||
To retrieve the help for any API within Vault, including mounted backends, auth
|
||||
To retrieve the help for any API within Vault, including mounted engines, auth
|
||||
methods, etc. then append `?help=1` to any URL. If you have valid permission to
|
||||
access the path, then the help text will be return a markdown-formatted block in the `help` attribute of the response.
|
||||
access the path, then the help text will be returned as a markdown-formatted block
|
||||
in the `help` attribute of the response.
|
||||
|
||||
Additionally, with the [OpenAPI generation](/api/system/internal-specs-openapi) in Vault, you will get back a small
|
||||
OpenAPI document in the `openapi` attribute. This document is relevant for the
|
||||
path you're looking up and any paths under it - also note paths in the OpenAPI
|
||||
document are relative to the initial path queried.
|
||||
|
||||
Additionally, with the [OpenAPI generation](/api-docs/system/internal-specs-openapi) in Vault, you will get back a small
|
||||
OpenAPI document in the `openapi` attribute. This document is relevant for the path you're looking up and any paths under it - also note paths in the OpenAPI document are relative to the initial path queried.
|
||||
|
||||
Example request:
|
||||
|
||||
|
|
@ -258,14 +269,13 @@ A common JSON structure is always returned to return errors:
|
|||
}
|
||||
```
|
||||
|
||||
This structure will be sent down for any HTTP status greater than
|
||||
or equal to 400.
|
||||
This structure will be returned for any HTTP status greater than or equal to 400.
|
||||
|
||||
## HTTP Status Codes
|
||||
|
||||
The following HTTP status codes are used throughout the API. Vault tries to
|
||||
adhere to these whenever possible, but in some cases may not -- feel free to
|
||||
file a bug in that case to point our attention to it!
|
||||
adhere to these whenever possible, but in case it doesn't -- then feel free to
|
||||
[raise a bug](https://github.com/hashicorp/vault/issues) for our attention!
|
||||
|
||||
~> _Note_: Applications should be prepared to accept both `200` and `204` as
|
||||
success. `204` is simply an indication that there is no response body to parse,
|
||||
|
|
|
|||
Loading…
Reference in New Issue