Explore the Consul HTTP API

This page introduces the Consul HTTP API and describes the steps to set up and use the API to interact with Consul deployments.

For more information, refer to the Consul HTTP API reference documentation.

Introduction

The Consul HTTP API is a RESTful interface for Consul that exposes endpoints for both Consul operations and service networking functions that return JSON payloads.

You can interact with any Consul agent to use the HTTP API. When ACLs are enabled, you must provide a Consul token in a X-Consul-Token header to authenticate with Consul.

How Consul clusters respond to API requests

In production, a typical Consul datacenter consists of a cluster of 3 to 5 server agents in the control plane, and can potentially include thousands of client agents in the application's data plane. By default, Consul agents send each API request to the current leader of the server quorum in order to receive the most up-to-date information from the Consul catalog.

High request volumes to a single server can impact cluster performance. While Consul uses the gossip protocol to efficiently distribute updates across agents, this distributed approach means that agents may temporarily have different views of the cluster state. This eventual consistency model allows Consul to handle higher loads by spreading requests across multiple agents, rather than concentrating all traffic on a single server.

Consul includes several API features that help you manage this effect on your requests, especially when Consul operates at scale.

Consistency modes

All HTTP API read requests use the default consistency mode unless overridden on a per-request basis. We do not recommend changing the consistency mode used by default. You can use the stale or consistent query parameters on some endpoints to override the default setting. To learn more, refer to Consistency Modes.

Blocking queries

Many Consul API endpoints support blocking queries. In a blocking query, Consul waits until an update occurs and then returns a response to the HTTP request. Because connections can remain open without updates occuring, configure timeouts to control blocking query behavior. Blocking queries are an important part of some of Consul's advanced networking automations. To learn more, refer to Blocking Queries in the Consul API documentation.

Filtering

Consul supports a filter query parameter to include expressions for requests to match in the Consul catalog. Servers filter based on the expression before returning a response, which can greatly reduce operational load at scale. To learn more, refer to Filtering.

Agent cache

Some read endpoints in Consul can return results from the local agent's cache, instead of contacting the servers for results. You can use the ?cached query parameter and the Cache-Control header to enabled and define agent cache behavior. On some endpoints, you also have the option to enabled background refresh caching, which uses blocking queries to update the local agent cache when updates occur on the servers. For more information, refer to Agent caching.

Basic API requests

In a datacenter where ACLs are not enabled, the following request returns a JSON payload that lists the the Consul instances that participated in the cluster's gossip pool, including their state. This HTTP API request corresponds to the consul members CLI command.

$ curl http://127.0.0.1:8500/v1/agent/members

The following request reloads the configuration files in the agent's configuration directory. Use this command to apply configuration updates to your Consul cluster without restarting the agent or node. This HTTP API request corresponds to the consul reload CLI command.

$ curl \
    --request PUT \
    http://127.0.0.1:8500/v1/agent/reload

The following request returns a list of nodes, including their IP address, where the web service was registered. You can use filtering query parameters to refine the list of services that API request returns.

$ curl http://127.0.0.1:8500/v1/catalog/service/web

Next steps

To learn more about the Consul HTTP API and its endpoints, refer to the Consul API documentation.

To continue learning Consul fundamentals, proceed to either Explore the Consul CLI or Explore the Consul web UI.