162 lines
5.4 KiB
Plaintext
162 lines
5.4 KiB
Plaintext
---
|
|
layout: api
|
|
page_title: HTTP API
|
|
description: |-
|
|
Consul exposes a RESTful HTTP API to control almost every aspect of the
|
|
Consul agent.
|
|
---
|
|
|
|
# HTTP API Structure
|
|
|
|
The main interface to Consul is a RESTful HTTP API. The API can perform basic
|
|
CRUD operations on nodes, services, checks, configuration, and more.
|
|
|
|
## Authentication
|
|
|
|
When authentication is enabled, a Consul token should be provided to API
|
|
requests using the `X-Consul-Token` header or with the
|
|
Bearer scheme in the authorization header.
|
|
This reduces the probability of the
|
|
token accidentally getting logged or exposed. When using authentication,
|
|
clients should communicate via TLS.
|
|
|
|
If no token is provided for an HTTP request then Consul will use the default ACL token
|
|
if it has been configured. If no default ACL token was configured then the anonymous
|
|
token will be used.
|
|
|
|
Below is an example using `curl` with `X-Consul-Token`.
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--header "X-Consul-Token: <consul token>" \
|
|
http://127.0.0.1:8500/v1/agent/members
|
|
```
|
|
|
|
Below is an example using `curl` with a [RFC6750](https://tools.ietf.org/html/rfc6750) Bearer token.
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--header "Authorization: Bearer <consul token>" \
|
|
http://127.0.0.1:8500/v1/agent/members
|
|
```
|
|
|
|
Previously this was provided via a `?token=` query parameter. This functionality
|
|
exists on many endpoints for backwards compatibility, but its use is **highly
|
|
discouraged**, since it can show up in access logs as part of the URL.
|
|
|
|
To learn more about the ACL system read the [documentation](/docs/security/acl).
|
|
|
|
## Version Prefix
|
|
|
|
All API routes are prefixed with `/v1/`. This documentation is only for the v1 API.
|
|
|
|
## Formatted JSON Output
|
|
|
|
By default, the output of all HTTP API requests is minimized JSON. If the client
|
|
passes `pretty` on the query string, formatted JSON will be returned.
|
|
|
|
## HTTP Methods
|
|
|
|
Consul's API aims to be RESTful, although there are some exceptions. The API
|
|
responds to the standard HTTP verbs GET, PUT, and DELETE. Each API method will
|
|
clearly document the verb(s) it responds to and the generated response. The same
|
|
path with different verbs may trigger different behavior. For example:
|
|
|
|
```text
|
|
PUT /v1/kv/foo
|
|
GET /v1/kv/foo
|
|
```
|
|
|
|
Even though these share a path, the `PUT` operation creates a new key whereas
|
|
the `GET` operation reads an existing key.
|
|
|
|
Here is the same example using `curl`:
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request PUT \
|
|
--data 'hello consul' \
|
|
http://127.0.0.1:8500/v1/kv/foo
|
|
```
|
|
|
|
## URL-Encoded Resource Names
|
|
|
|
Some Consul HTTP API endpoints accept resource names in URL path or query parameters.
|
|
To pass a resource name containing URL-invalid characters, such as `/` or ` `,
|
|
URL-encode the resource name into the URL.
|
|
|
|
However, we generally recommend using resource names that don't require URL-encoding.
|
|
Depending on the validation that Consul applies to a resource name,
|
|
Consul may still reject a request if it considers the resource name invalid for that endpoint.
|
|
And even if Consul considers the resource name valid, it may degrade other functionality,
|
|
such as failed [DNS lookups](/docs/discovery/dns)
|
|
for nodes or services with names containing invalid DNS characters.
|
|
|
|
This HTTP API capability also allows the
|
|
[CLI to accept arguments with URL-invalid characters](/commands#arguments-with-url-invalid-characters).
|
|
|
|
### Invalid Characters
|
|
|
|
The linefeed character (`%0a`) will cause a request to be rejected even if it is URL-encoded.
|
|
|
|
## Translated Addresses
|
|
|
|
Consul 0.7 added the ability to translate addresses in HTTP response based on
|
|
the configuration setting for
|
|
[`translate_wan_addrs`](/docs/agent/config/config-files#translate_wan_addrs). In order
|
|
to allow clients to know if address translation is in effect, the
|
|
`X-Consul-Translate-Addresses` header will be added if translation is enabled,
|
|
and will have a value of `true`. If translation is not enabled then this header
|
|
will not be present.
|
|
|
|
## Default ACL Policy
|
|
|
|
All API responses for Consul versions after 1.9 will include an HTTP response
|
|
header `X-Consul-Default-ACL-Policy` set to either "allow" or "deny" which
|
|
mirrors the current value of the agent's
|
|
[`acl.default_policy`](/docs/agent/config/config-files#acl_default_policy) option.
|
|
|
|
This is also the default [intention](/docs/connect/intentions) enforcement
|
|
action if no intention matches.
|
|
|
|
This is returned even if ACLs are disabled.
|
|
|
|
## Results Filtered by ACLs
|
|
|
|
As of Consul 1.11, most list endpoints support an `X-Consul-Results-Filtered-By-ACLs`
|
|
HTTP response header. This indicates that the response contains a partial subset
|
|
of results, because some have been filtered out by ACL policies.
|
|
|
|
In order to limit information leakage, this header is only present for requests
|
|
authenticated by a valid ACL token.
|
|
|
|
The following example uses `curl` to view the
|
|
`X-Consul-Results-Filtered-By-ACLs` response header.
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--header "X-Consul-Token: <non-anonymous consul token>" \
|
|
--include \
|
|
http://127.0.0.1:8500/v1/catalog/services
|
|
|
|
HTTP/1.1 200 OK
|
|
Content-Type: application/json
|
|
...
|
|
X-Consul-Default-Acl-Policy: deny
|
|
X-Consul-Results-Filtered-By-Acls: true
|
|
|
|
{
|
|
"redis": [],
|
|
"postgresql": ["primary", "secondary"]
|
|
}
|
|
```
|
|
|
|
## UUID Format
|
|
|
|
UUID-format identifiers generated by the Consul API use the
|
|
[hashicorp/go-uuid](https://github.com/hashicorp/go-uuid) library.
|
|
|
|
These UUID-format strings are generated using high quality, purely random bytes.
|
|
It is not intended to be RFC compliant, merely to use a well-understood string
|
|
representation of a 128-bit value.
|