2017-04-04 16:33:22 +00:00
|
|
|
|
---
|
|
|
|
|
layout: api
|
|
|
|
|
page_title: HTTP API
|
2020-04-07 18:55:19 +00:00
|
|
|
|
sidebar_title: 'API Introduction'
|
2019-04-16 16:00:15 +00:00
|
|
|
|
sidebar_current: api-introduction
|
2017-04-04 16:33:22 +00:00
|
|
|
|
description: |-
|
|
|
|
|
Consul exposes a RESTful HTTP API to control almost every aspect of the
|
|
|
|
|
Consul agent.
|
|
|
|
|
---
|
|
|
|
|
|
2019-04-16 16:00:15 +00:00
|
|
|
|
# HTTP API Structure
|
2017-04-04 16:33:22 +00:00
|
|
|
|
|
2018-01-08 17:02:10 +00:00
|
|
|
|
The main interface to Consul is a RESTful HTTP API. The API can perform basic
|
2017-04-04 16:33:22 +00:00
|
|
|
|
CRUD operations on nodes, services, checks, configuration, and more.
|
|
|
|
|
|
|
|
|
|
## Authentication
|
|
|
|
|
|
|
|
|
|
When authentication is enabled, a Consul token should be provided to API
|
2019-04-30 17:20:51 +00:00
|
|
|
|
requests using the `X-Consul-Token` header or with the
|
2020-04-06 20:27:35 +00:00
|
|
|
|
Bearer scheme in the authorization header.
|
2019-04-30 17:20:51 +00:00
|
|
|
|
This reduces the probability of the
|
2018-01-08 17:02:10 +00:00
|
|
|
|
token accidentally getting logged or exposed. When using authentication,
|
2019-04-30 17:20:51 +00:00
|
|
|
|
clients should communicate via TLS. If you don’t provide a token in the request, then the agent default token will be used.
|
2017-04-04 16:33:22 +00:00
|
|
|
|
|
2019-04-30 17:20:51 +00:00
|
|
|
|
Below is an example using `curl` with `X-Consul-Token`.
|
|
|
|
|
|
2020-04-07 23:56:08 +00:00
|
|
|
|
```shell
|
2019-04-30 17:20:51 +00:00
|
|
|
|
$ 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.
|
|
|
|
|
|
2020-04-07 23:56:08 +00:00
|
|
|
|
```shell
|
2017-04-04 16:33:22 +00:00
|
|
|
|
$ curl \
|
2019-04-30 17:20:51 +00:00
|
|
|
|
--header "Authorization: Bearer <consul token>" \
|
2018-08-28 16:07:15 +00:00
|
|
|
|
http://127.0.0.1:8500/v1/agent/members
|
2017-04-04 16:33:22 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2019-04-30 17:20:51 +00:00
|
|
|
|
To learn more about the ACL system read the [documentation](/docs/acl/acl-system.html).
|
|
|
|
|
|
2019-04-16 16:00:15 +00:00
|
|
|
|
## Version Prefix
|
2018-09-06 10:34:28 +00:00
|
|
|
|
|
2019-04-16 16:00:15 +00:00
|
|
|
|
All API routes are prefixed with `/v1/`. This documentation is only for the v1 API.
|
2018-09-06 10:34:28 +00:00
|
|
|
|
|
2017-04-04 16:33:22 +00:00
|
|
|
|
## 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
|
|
|
|
|
$ curl \
|
|
|
|
|
--request PUT \
|
|
|
|
|
--data 'hello consul' \
|
2018-08-28 16:07:15 +00:00
|
|
|
|
http://127.0.0.1:8500/v1/kv/foo
|
2017-04-04 16:33:22 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## 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.html#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.
|
2018-11-29 21:23:58 +00:00
|
|
|
|
|
|
|
|
|
## 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.
|