Consul is a distributed, highly available, and data center aware solution to connect and configure applications across dynamic, distributed infrastructure.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

161 lines
5.5 KiB

---
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
```
**Security Note:** Though you could pass the token through the `?token=` query parameter,
this method is highly discouraged because the token can show up in access logs as part of the URL.
The `?token=` query parameter is deprecated and will be removed in Consul 1.17.
To learn more about the ACL system read the [documentation](/consul/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](/consul/docs/services/discovery/dns-overview)
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](/consul/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`](/consul/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`](/consul/docs/agent/config/config-files#acl_default_policy) option.
This is also the default [intention](/consul/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.