mirror of https://github.com/status-im/consul.git
Begin editing the docs/agent/http.
This commit is contained in:
Ryan Breen
parent
3a184a06f7
commit
27c145e2f8
|
|
@ -3,96 +3,93 @@ layout: "docs"
|
|||
page_title: "HTTP API"
|
||||
sidebar_current: "docs-agent-http"
|
||||
description: |-
|
||||
The main interface to Consul is a RESTful HTTP API. The API can be used for CRUD for nodes, services, checks, and configuration. The endpoints are versioned to enable changes without breaking backwards compatibility.
|
||||
The main interface to Consul is a RESTful HTTP API. The API can be used to perform CRUD operations on nodes, services, checks, configuration, and more. The endpoints are versioned to enable changes without breaking backwards compatibility.
|
||||
---
|
||||
|
||||
# HTTP API
|
||||
|
||||
The main interface to Consul is a RESTful HTTP API. The API can be
|
||||
used for CRUD for nodes, services, checks, and configuration. The endpoints are
|
||||
versioned to enable changes without breaking backwards compatibility.
|
||||
The main interface to Consul is a RESTful HTTP API. The API can be used to perform CRUD
|
||||
operations on nodes, services, checks, configuration, and more. The endpoints are versioned
|
||||
to enable changes without breaking backwards compatibility.
|
||||
|
||||
All endpoints fall into one of several categories:
|
||||
Each endpoint manages a different aspect of Consul:
|
||||
|
||||
* [kv](http/kv.html) - Key/Value store
|
||||
* [agent](http/agent.html) - Agent control
|
||||
* [catalog](http/catalog.html) - Manages nodes and services
|
||||
* [health](http/health.html) - Manages health checks
|
||||
* [session](http/session.html) - Session manipulation
|
||||
* [acl](http/acl.html) - ACL creations and management
|
||||
* [agent](http/agent.html) - Consul Agent
|
||||
* [catalog](http/catalog.html) - Modes and services
|
||||
* [health](http/health.html) - Health checks
|
||||
* [session](http/session.html) - Sessions
|
||||
* [acl](http/acl.html) - Access Control Lists
|
||||
* [event](http/event.html) - User Events
|
||||
* [status](http/status.html) - Consul system status
|
||||
* internal - Internal APIs. Purposely undocumented, subject to change.
|
||||
|
||||
Each of the categories and their respective endpoints are documented below.
|
||||
Each of these is documented in detail at the links above.
|
||||
|
||||
## Blocking Queries
|
||||
|
||||
Certain endpoints support a feature called a "blocking query." A blocking query
|
||||
is used to wait for a change to potentially take place using long polling.
|
||||
is used to wait for a potential change using long polling.
|
||||
|
||||
Queries that support this will mention it specifically, however the use of this
|
||||
feature is the same for all. If supported, the query will set an HTTP header
|
||||
"X-Consul-Index". This is an opaque handle that the client will use.
|
||||
Not all endpoints support blocking, but those that do are clearly designated in the
|
||||
documentations. Any endpoint that supports blocking will also set the HTTP header
|
||||
`X-Consul-Index`, a unique identifier representing the current state of this
|
||||
requested resource. When again requesting this resource, the client can set the `index`
|
||||
query string parameter to the value of "X-Consul-Index", indicating that it wishes to wait
|
||||
for any changes subsequent to that index.
|
||||
|
||||
To cause a query to block, the query parameters "?wait=\<interval\>&index=\<idx\>" are added
|
||||
to a request. The "?wait=" query parameter limits how long the query will potentially
|
||||
block for. It not set, it will default to 10 minutes. It can be specified in the form of
|
||||
"10s" or "5m", which is 10 seconds or 5 minutes respectively. The "?index=" parameter is an
|
||||
opaque handle, which is used by Consul to detect changes. The "X-Consul-Index" header for a
|
||||
query provides this value, and can be used to wait for changes since the query was run.
|
||||
In addition to `index`, endpoints that support blocking will also honor a `wait`
|
||||
parameter specifying a maximum duration for the blocking request. It not set, it will
|
||||
default to 10 minutes. This value can be specified in the form of "10s" or "5m" (i.e.,
|
||||
10 seconds or 5 minutes, respectively).
|
||||
|
||||
When provided, Consul blocks sending a response until there is an update that
|
||||
could have cause the output to change, and thus advancing the index. A critical
|
||||
note is that when the query returns there is **no guarantee** of a change. It is
|
||||
possible that the timeout was reached, or that there was an idempotent write that
|
||||
does not affect the result.
|
||||
A critical note is that the return of a blocking request is **no guarantee** of a change. It
|
||||
is possible that the timeout was reached or that there was an idempotent write that does
|
||||
not affect the result of the query.
|
||||
|
||||
## Consistency Modes
|
||||
|
||||
Most of the read query endpoints support multiple levels of consistency.
|
||||
These are to provide a tuning knob that clients can be used to find a happy
|
||||
medium that best matches their needs.
|
||||
Most of the read query endpoints support multiple levels of consistency. Since no policy will
|
||||
suit all clients' needs, these consistency modes allow the user to have the ultimate say in
|
||||
how to balance the trade-offs inherent in a distributed system.
|
||||
|
||||
The three read modes are:
|
||||
|
||||
* default - If not specified, this mode is used. It is strongly consistent
|
||||
in almost all cases. However, there is a small window in which an new
|
||||
leader may be elected, and the old leader may service stale values. The
|
||||
trade off is fast reads, but potentially stale values. This condition is
|
||||
hard to trigger, and most clients should not need to worry about the stale read.
|
||||
This only applies to reads, and a split-brain is not possible on writes.
|
||||
* default - If not specified, the default is strongly consistent in almost all cases. However,
|
||||
there is a small window in which a new leader may be elected during which the old leader may
|
||||
service stale values. The trade-off is fast reads but potentially stale values. The condition
|
||||
resulting in stale reads is hard to trigger, and most clients should not need to worry about
|
||||
this case. Also, note that this race condition only applies to reads, not writes.
|
||||
|
||||
* consistent - This mode is strongly consistent without caveats. It requires
|
||||
that a leader verify with a quorum of peers that it is still leader. This
|
||||
introduces an additional round-trip to all server nodes. The trade off is
|
||||
always consistent reads, but increased latency due to an extra round trip.
|
||||
Most clients should not use this unless they cannot tolerate a stale read.
|
||||
introduces an additional round-trip to all server nodes. The trade-off is
|
||||
increased latency due to an extra round trip. Most clients should not use this
|
||||
unless they cannot tolerate a stale read.
|
||||
|
||||
* stale - This mode allows any server to service the read, regardless of if
|
||||
it is the leader. This means reads can be arbitrarily stale, but are generally
|
||||
within 50 milliseconds of the leader. The trade off is very fast and scalable
|
||||
reads but values will be stale. This mode allows reads without a leader, meaning
|
||||
a cluster that is unavailable will still be able to respond.
|
||||
* stale - This mode allows any server to service the read regardless of if
|
||||
it is the leader. This means reads can be arbitrarily stale but are generally
|
||||
consistent to within 50 milliseconds of the leader. The trade-off is very fast and
|
||||
scalable reads with a higher likelihood of stale values. This mode allows reads without
|
||||
a leader, meaning a cluster that is unavailable will still be able to respond to queries.
|
||||
|
||||
To switch these modes, either the "?stale" or "?consistent" query parameters
|
||||
are provided. It is an error to provide both.
|
||||
To switch these modes, either the `stale` or `consistent` query parameters
|
||||
should be provided on requests. It is an error to provide both.
|
||||
|
||||
To support bounding how stale data is, there is an "X-Consul-LastContact"
|
||||
which is the last time a server was contacted by the leader node in
|
||||
milliseconds. The "X-Consul-KnownLeader" also indicates if there is a known
|
||||
leader. These can be used to gauge if a stale read should be used.
|
||||
To support bounding the acceptable staleness of data, responses provide the `X-Consul-LastContact`
|
||||
header containing the time in milliseconds that a server was last contacted by the leader node.
|
||||
The `X-Consul-KnownLeader` header also indicates if there is a known leader. These can be used
|
||||
by clients to gauge the staleness of a result and take appropriate action.
|
||||
|
||||
## Formatted JSON Output
|
||||
|
||||
By default, the output of all HTTP API requests return minimized JSON with all
|
||||
whitespace removed. By adding "?pretty" to the HTTP request URL,
|
||||
formatted JSON will be returned.
|
||||
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.
|
||||
|
||||
## ACLs
|
||||
|
||||
Several endpoints in Consul use or require ACL tokens to operate. An agent
|
||||
can be configured to use a default token in requests using the `acl_token`
|
||||
configuration option. However, the token can also be specified per-request
|
||||
by using the "?token=" query parameter. This will take precedence over the
|
||||
by using the `token` query parameter. This will take precedent over the
|
||||
default token.
|
||||
|
|
|
|||
Loading…
Reference in New Issue