d81889bb41
Avoid HTTP redirects for internal site links by updating old URLs to point to the new location for the target content.
117 lines
3.9 KiB
Plaintext
117 lines
3.9 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 you don’t provide a token in the request, then the agent default 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 Bearer scheme.
|
||
|
||
```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/acl-system).
|
||
|
||
## 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
|
||
```
|
||
|
||
## 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/options#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/options#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.
|
||
|
||
## 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.
|