Merge pull request #678 from ryanbreen/agent

Cleanup for docs/agent/http/agent.

website/source/docs/agent/http/agent.html.markdown

@@ -3,41 +3,41 @@ layout: "docs"
 page_title: "Agent (HTTP)"
 sidebar_current: "docs-agent-http-agent"
 description: >
-  The Agent endpoints are used to interact with a local Consul agent.
+  The Agent endpoints are used to interact with the local Consul agent.
 ---
 
 # Agent HTTP Endpoint
 
-The Agent endpoints are used to interact with a local Consul agent. Usually,
+The Agent endpoints are used to interact with the local Consul agent. Usually,
-services and checks are registered with an agent, which then takes on the
+services and checks are registered with an agent which then takes on the
-burden of registering with the Catalog and performing anti-entropy to recover from
+burden of keeping that data synchronized with the cluster.  For example, the
-outages. There are also various control APIs that can be used instead of the
+agent registers services and checks with the Catalog and performs anti-entropy
-msgpack RPC protocol.
+to recover from outages.
 
 The following endpoints are supported:
 
 * [`/v1/agent/checks`](#agent_checks) : Returns the checks the local agent is managing
-* [`/v1/agent/services`](#agent_services) : Returns the services local agent is managing
+* [`/v1/agent/services`](#agent_services) : Returns the services the local agent is managing
 * [`/v1/agent/members`](#agent_members) : Returns the members as seen by the local serf agent
 * [`/v1/agent/self`](#agent_self) : Returns the local node configuration
-* [`/v1/agent/maintenance`](#agent_maintenance) : Node maintenance mode
+* [`/v1/agent/maintenance`](#agent_maintenance) : Manages node maintenance mode
-* [`/v1/agent/join/<address>`](#agent_join) : Trigger local agent to join a node
+* [`/v1/agent/join/<address>`](#agent_join) : Triggers the local agent to join a node
-* [`/v1/agent/force-leave/<node>`](#agent_force_leave)>: Force remove node
+* [`/v1/agent/force-leave/<node>`](#agent_force_leave)>: Forces removal of a node
 * [`/v1/agent/check/register`](#agent_check_register) : Registers a new local check
-* [`/v1/agent/check/deregister/<checkID>`](#agent_check_deregister) : Deregister a local check
+* [`/v1/agent/check/deregister/<checkID>`](#agent_check_deregister) : Deregisters a local check
-* [`/v1/agent/check/pass/<checkID>`](#agent_check_pass) : Mark a local test as passing
+* [`/v1/agent/check/pass/<checkID>`](#agent_check_pass) : Marks a local test as passing
-* [`/v1/agent/check/warn/<checkID>`](#agent_check_warn) : Mark a local test as warning
+* [`/v1/agent/check/warn/<checkID>`](#agent_check_warn) : Marks a local test as warning
-* [`/v1/agent/check/fail/<checkID>`](#agent_check_fail) : Mark a local test as critical
+* [`/v1/agent/check/fail/<checkID>`](#agent_check_fail) : Marks a local test as critical
 * [`/v1/agent/service/register`](#agent_service_register) : Registers a new local service
-* [`/v1/agent/service/deregister/<serviceID>`](#agent_service_deregister) : Deregister a local service
+* [`/v1/agent/service/deregister/<serviceID>`](#agent_service_deregister) : Deregisters a local service
-* [`/v1/agent/service/maintenance/<serviceID>`](#agent_service_maintenance) : Service maintenance mode
+* [`/v1/agent/service/maintenance/<serviceID>`](#agent_service_maintenance) : Manages service maintenance mode
 
 ### <a name="agent_checks"></a> /v1/agent/checks
 
-This endpoint is used to return the all the checks that are registered with
+This endpoint is used to return all the checks that are registered with
-the local agent. These checks were either provided through configuration files,
+the local agent. These checks were either provided through configuration files
 or added dynamically using the HTTP API. It is important to note that the checks
-known by the agent may be different than those reported by the Catalog. This is usually
+known by the agent may be different from those reported by the Catalog. This is usually
 due to changes being made while there is no leader elected. The agent performs active
 anti-entropy, so in most situations everything will be in sync within a few seconds.
 
@@ -61,9 +61,9 @@ This endpoint is hit with a GET and returns a JSON body like this:
 ### <a name="agent_services"></a> /v1/agent/services
 
 This endpoint is used to return the all the services that are registered with
-the local agent. These services were either provided through configuration files,
+the local agent. These services were either provided through configuration files
 or added dynamically using the HTTP API. It is important to note that the services
-known by the agent may be different than those reported by the Catalog. This is usually
+known by the agent may be different from those reported by the Catalog. This is usually
 due to changes being made while there is no leader elected. The agent performs active
 anti-entropy, so in most situations everything will be in sync within a few seconds.
 
@@ -83,15 +83,15 @@ This endpoint is hit with a GET and returns a JSON body like this:
 
 ### <a name="agent_members"></a> /v1/agent/members
 
-This endpoint is hit with a GET and returns the members the agent sees in the
+This endpoint is used to return the members the agent sees in the
-cluster gossip pool. Due to the nature of gossip, this is eventually consistent
+cluster gossip pool. Due to the nature of gossip, this is eventually consistent: the
-and the results may differ by agent. The strongly consistent view of nodes is
+results may differ by agent. The strongly consistent view of nodes is
 instead provided by "/v1/catalog/nodes".
 
 For agents running in server mode, providing a "?wan=1" query parameter returns
-the list of WAN members instead of the LAN members which is default.
+the list of WAN members instead of the LAN members returned by default.
 
-This endpoint returns a JSON body like:
+This endpoint is hit with a GET and returns a JSON body like:
 
 ```javascript
 [
@@ -118,7 +118,7 @@ This endpoint returns a JSON body like:
 
 ### <a name="agent_self"></a> /v1/agent/self
 
-This endpoint is used to return configuration of the local agent and member information.
+This endpoint is used to return the configuration and member information of the local agent.
 
 It returns a JSON body like this:
 
@@ -187,17 +187,17 @@ It returns a JSON body like this:
 
 ### <a name="agent_maintenance"></a> /v1/agent/maintenance
 
-The node maintenance endpoint allows placing the agent into "maintenance mode".
+The node maintenance endpoint can place the agent into "maintenance mode".
-During maintenance mode, the node will be marked as unavailable, and will not be
+During maintenance mode, the node will be marked as unavailable and will not be
 present in DNS or API queries. This API call is idempotent. Maintenance mode is
 persistent and will be automatically restored on agent restart.
 
-The `?enable` flag is required, and its value must be `true` (to enter
+The `?enable` flag is required.  Acceptable values are either `true` (to enter
-maintenance mode), or `false` (to resume normal operation).
+maintenance mode) or `false` (to resume normal operation).
 
-The `?reason` flag is optional, and can contain a text string explaining the
+The `?reason` flag is optional.  If provided, its value should be a text string
-reason for placing the node into maintenance mode. If no reason is provided,
+explaining the reason for placing the node into maintenance mode. This is simply
-a default value will be used instead.
+to aid human operators. If no reason is provided, a default value will be used instead.
 
 The return code is 200 on success.
 
@@ -207,14 +207,14 @@ This endpoint is hit with a GET and is used to instruct the agent to attempt to
 connect to a given address.  For agents running in server mode, providing a "?wan=1"
 query parameter causes the agent to attempt to join using the WAN pool.
 
-The endpoint returns 200 on successful join.
+The return code is 200 on success.
 
 ### <a name="agent_force_leave"></a> /v1/agent/force-leave/\<node\>
 
-This endpoint is hit with a GET and is used to instructs the agent to force a node into the left state.
+This endpoint is hit with a GET and is used to instruct the agent to force a node into the `left` state.
-If a node fails unexpectedly, then it will be in a "failed" state. Once in this state, Consul will
+If a node fails unexpectedly, then it will be in a `failed` state. Once in the `failed` state, Consul will
-attempt to reconnect, and additionally the services and checks belonging to that node will not be
+attempt to reconnect, and the services and checks belonging to that node will not be
-cleaned up. Forcing a node into the left state allows its old entries to be removed.
+cleaned up. Forcing a node into the `left` state allows its old entries to be removed.
 
 The endpoint always returns 200.
 
@@ -222,7 +222,7 @@ The endpoint always returns 200.
 
 The register endpoint is used to add a new check to the local agent.
 There is more documentation on checks [here](/docs/agent/checks.html).
-Checks are of script, HTTP, or TTL type. The agent is responsible for managing
+Checks may be of script, HTTP, or TTL type. The agent is responsible for managing
 the status of the check and keeping the Catalog in sync.
 
 The register endpoint expects a JSON request body to be PUT. The request
@@ -244,66 +244,69 @@ The `Name` field is mandatory, as is one of `Script`, `HTTP` or `TTL`.
 `Script` and `HTTP` also require that `Interval` be set.
 
 If an `ID` is not provided, it is set to `Name`. You cannot have duplicate
-`ID` entries per agent, so it may be necessary to provide an ID. The `Notes`
+`ID` entries per agent, so it may be necessary to provide an `ID`.
-field is not used by Consul, and is meant to be human readable.
+
+The `Notes` field is not used internally by Consul and is meant to be human-readable.
 
 If a `Script` is provided, the check type is a script, and Consul will
 evaluate the script every `Interval` to update the status.
 
-An `HTTP` check will perform an HTTP GET request to the value of `HTTP` (expected to be a URL) every `Interval`. If the response is any `2xx` code the check is passing, if the response is `429 Too Many Requests` the check is warning, otherwise the check is critical.
+An `HTTP` check will perform an HTTP GET request against the value of `HTTP` (expected to
+be a URL) every `Interval`. If the response is any `2xx` code, the check is `passing`.
+If the response is `429 Too Many Requests`, the check is `warning`. Otherwise, the check
+is `critical`.
 
-If a `TTL` type is used, then the TTL update APIs must be used to periodically update
+If a `TTL` type is used, then the TTL update endpoint must be used periodically to update
 the state of the check.
 
 The return code is 200 on success.
 
 ### <a name="agent_check_deregister"></a> /v1/agent/check/deregister/\<checkId\>
 
-The deregister endpoint is used to remove a check from the local agent.
+This endpoint is used to remove a check from the local agent.
-The CheckID must be passed after the slash. The agent will take care
+The `CheckID` must be passed on the path. The agent will take care
-of deregistering the check with the Catalog.
+of deregistering the check from the Catalog.
 
 The return code is 200 on success.
 
 ### <a name="agent_check_pass"></a> /v1/agent/check/pass/\<checkId\>
 
 This endpoint is used with a check that is of the [TTL type](/docs/agent/checks.html).
-When this endpoint is accessed via a GET, the status of the check is set to "passing",
+When this endpoint is accessed via a GET, the status of the check is set to `passing`
 and the TTL clock is reset.
 
-The optional "?note=" query parameter can be used to associate output with
+The optional "?note=" query parameter can be used to associate a human-readable message 
-the status of the check. This should be human readable for operators.
+with the status of the check.
 
 The return code is 200 on success.
 
 ### <a name="agent_check_warn"></a> /v1/agent/check/warn/\<checkId\>
 
 This endpoint is used with a check that is of the [TTL type](/docs/agent/checks.html).
-When this endpoint is accessed via a GET, the status of the check is set to "warning",
+When this endpoint is accessed via a GET, the status of the check is set to `warning`,
 and the TTL clock is reset.
 
-The optional "?note=" query parameter can be used to associate output with
+The optional "?note=" query parameter can be used to associate a human-readable message 
-the status of the check. This should be human readable for operators.
+with the status of the check.
 
 The return code is 200 on success.
 
 ### <a name="agent_check_fail"></a> /v1/agent/check/fail/\<checkId\>
 
 This endpoint is used with a check that is of the [TTL type](/docs/agent/checks.html).
-When this endpoint is accessed via a GET, the status of the check is set to "critical",
+When this endpoint is accessed via a GET, the status of the check is set to `critical`,
 and the TTL clock is reset.
 
-The optional "?note=" query parameter can be used to associate output with
+The optional "?note=" query parameter can be used to associate a human-readable message 
-the status of the check. This should be human readable for operators.
+with the status of the check.
 
 The return code is 200 on success.
 
 ### <a name="agent_service_register"></a> /v1/agent/service/register
 
-The register endpoint is used to add a new service to the local agent.
+The register endpoint is used to add a new service, with an optional health check,
-There is more documentation on services [here](/docs/agent/services.html).
+to the local agent. There is more documentation on services [here](/docs/agent/services.html).
-Services may also provide a health check. The agent is responsible for managing
+The agent is responsible for managing the status of the service and keeping the Catalog in sync.
-the status of the check and keeping the Catalog in sync.
 
 The register endpoint expects a JSON request body to be PUT. The request
 body must look like:
@@ -328,14 +331,16 @@ body must look like:
 ```
 
 The `Name` field is mandatory,  If an `ID` is not provided, it is set to `Name`.
-You cannot have duplicate `ID` entries per agent, so it may be necessary to provide an ID.
+You cannot have duplicate `ID` entries per agent, so it may be necessary to provide an ID
+in the case of a collision.
+
 `Tags`, `Address`, `Port` and `Check` are optional.
-If `Check` is provided, only one of `Script`, `HTTP` or `TTL` should be provided.
-`Script` and `HTTP` also require `Interval`.
-There is more information about checks [here](/docs/agent/checks.html).
-The `Address` will default to that of the agent if not provided.
 
-The created check will be named "service:\<ServiceId\>".
+`Address` will default to that of the agent if not provided.
+
+If `Check` is provided, only one of `Script`, `HTTP`, or `TTL` should be specified.
+`Script` and `HTTP` also require `Interval`. The created check will be named "service:\<ServiceId\>".
+There is more information about checks [here](/docs/agent/checks.html).
 
 The return code is 200 on success.
 
@@ -352,15 +357,15 @@ The return code is 200 on success.
 
 The service maintenance endpoint allows placing a given service into
 "maintenance mode". During maintenance mode, the service will be marked as
-unavailable, and will not be present in DNS or API queries. This API call is
+unavailable and will not be present in DNS or API queries. This API call is
 idempotent. Maintenance mode is persistent and will be automatically restored
 on agent restart.
 
-The `?enable` flag is required, and its value must be `true` (to enter
+The `?enable` flag is required.  Acceptable values are either `true` (to enter
-maintenance mode), or `false` (to resume normal operation).
+maintenance mode) or `false` (to resume normal operation).
 
-The `?reason` flag is optional, and can contain a text string explaining the
+The `?reason` flag is optional.  If provided, its value should be a text string
-reason for placing the service into maintenance mode. If no reason is provided,
+explaining the reason for placing the service into maintenance mode. This is simply
-a default value will be used instead.
+to aid human operators. If no reason is provided, a default value will be used instead.
 
 The return code is 200 on success.