From 27c145e2f83a62d8876517ede84cbbb3db52ca38 Mon Sep 17 00:00:00 2001 From: Ryan Breen Date: Sun, 1 Feb 2015 17:42:02 -0500 Subject: [PATCH 1/2] Begin editing the docs/agent/http. --- website/source/docs/agent/http.html.markdown | 103 +++++++++---------- 1 file changed, 50 insertions(+), 53 deletions(-) diff --git a/website/source/docs/agent/http.html.markdown b/website/source/docs/agent/http.html.markdown index aeb0537922..69f6fe1311 100644 --- a/website/source/docs/agent/http.html.markdown +++ b/website/source/docs/agent/http.html.markdown @@ -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=\&index=\" 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. From 0d8ec874563fac7d84e4de89ee5d894ee64aa796 Mon Sep 17 00:00:00 2001 From: Ryan Breen Date: Mon, 2 Feb 2015 00:14:16 -0500 Subject: [PATCH 2/2] Some further cleanups to the root http doc. --- website/source/docs/agent/http.html.markdown | 22 ++++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/website/source/docs/agent/http.html.markdown b/website/source/docs/agent/http.html.markdown index 69f6fe1311..7ada4d670f 100644 --- a/website/source/docs/agent/http.html.markdown +++ b/website/source/docs/agent/http.html.markdown @@ -16,7 +16,7 @@ Each endpoint manages a different aspect of Consul: * [kv](http/kv.html) - Key/Value store * [agent](http/agent.html) - Consul Agent -* [catalog](http/catalog.html) - Modes and services +* [catalog](http/catalog.html) - Nodes and services * [health](http/health.html) - Health checks * [session](http/session.html) - Sessions * [acl](http/acl.html) - Access Control Lists @@ -32,14 +32,14 @@ Certain endpoints support a feature called a "blocking query." A blocking query is used to wait for a potential change using long polling. 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. +documentation. Any endpoint that supports blocking will also set the HTTP header +`X-Consul-Index`, a unique identifier representing the current state of the +requested resource. On subsequent requests for this resource, the client can set the `index` +query string parameter to the value of `X-Consul-Index`, indicating that the client wishes +to wait for any changes subsequent to that index. 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 +parameter specifying a maximum duration for the blocking request. If 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). @@ -67,11 +67,11 @@ The three read modes are: 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 +* stale - This mode allows any server to service the read regardless of whether + it is the leader. This means reads can be arbitrarily stale; however, results 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. + scalable reads with a higher likelihood of stale values. Since this mode allows reads without + a leader, a cluster that is unavailable will still be able to respond to queries. To switch these modes, either the `stale` or `consistent` query parameters should be provided on requests. It is an error to provide both.