diff --git a/website/source/docs/agent/http.html.markdown b/website/source/docs/agent/http.html.markdown index 88e555c822..7ae4988d81 100644 --- a/website/source/docs/agent/http.html.markdown +++ b/website/source/docs/agent/http.html.markdown @@ -14,14 +14,14 @@ versioned to enable changes without breaking backwards compatibility. All endpoints fall into one of several categories: -* kv - Key/Value store -* agent - Agent control -* catalog - Manages nodes and services -* health - Manages health checks -* session - Session manipulation -* acl - ACL creations and management -* event - User Events -* status - Consul system status +* [kv][kv] - Key/Value store +* [agent][agent] - Agent control +* [catalog][catalog] - Manages nodes and services +* [health][health] - Manages health checks +* [session][session] - Session manipulation +* [acl][acl] - ACL creations and management +* [event][event] - User Events +* [status][status] - Consul system status * internal - Internal APIs. Purposely undocumented, subject to change. Each of the categories and their respective endpoints are documented below. @@ -97,7 +97,7 @@ configuration option. However, the token can also be specified per-request by using the "?token=" query parameter. This will take precedence over the default token. -## KV +## KV The KV endpoint is used to expose a simple key/value store. This can be used to store service configurations or other meta data in a simple way. It has only @@ -213,7 +213,7 @@ keys sharing a prefix. If the "?recurse" query parameter is provided, then all keys with the prefix are deleted, otherwise only the specified key. -## Agent +## Agent The Agent endpoints are used to interact with a local Consul agent. Usually, services and checks are registered with an agent, which then takes on the @@ -223,21 +223,21 @@ msgpack RPC protocol. The following endpoints are supported: -* /v1/agent/checks : Returns the checks the local agent is managing -* /v1/agent/services : Returns the services local agent is managing -* /v1/agent/members : Returns the members as seen by the local serf agent -* /v1/agent/self : Returns the local node configuration -* /v1/agent/join/\ : Trigger local agent to join a node -* /v1/agent/force-leave/\: Force remove node -* /v1/agent/check/register : Registers a new local check -* /v1/agent/check/deregister/\ : Deregister a local check -* /v1/agent/check/pass/\ : Mark a local test as passing -* /v1/agent/check/warn/\ : Mark a local test as warning -* /v1/agent/check/fail/\ : Mark a local test as critical -* /v1/agent/service/register : Registers a new local service -* /v1/agent/service/deregister/\ : Deregister a local service +* [`/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/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/join/\`](#agent_join) : Trigger local agent to join a node +* [`/v1/agent/force-leave/\: Force remove node +* [`/v1/agent/check/register`](#agent_check_register) : Registers a new local check +* [`/v1/agent/check/deregister/\`](#agent_check_deregister) : Deregister a local check +* [`/v1/agent/check/pass/\`](#agent_check_pass) : Mark a local test as passing +* [`/v1/agent/check/warn/\`](#agent_check_warn) : Mark a local test as warning +* [`/v1/agent/check/fail/\`](#agent_check_fail) : Mark a local test as critical +* [`/v1/agent/service/register`](#agent_service_register) : Registers a new local service +* [`/v1/agent/service/deregister/\`](#agent_service_deregister) : Deregister a local service -### /v1/agent/checks +### /v1/agent/checks This endpoint is used to return the all the checks that are registered with the local agent. These checks were either provided through configuration files, @@ -263,7 +263,7 @@ This endpoint is hit with a GET and returns a JSON body like this: } ``` -### /v1/agent/services +### /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, @@ -285,7 +285,7 @@ This endpoint is hit with a GET and returns a JSON body like this: } ``` -### /v1/agent/members +### /v1/agent/members This endpoint is hit with a GET and returns the members the agent sees in the cluster gossip pool. Due to the nature of gossip, this is eventually consistent @@ -320,7 +320,7 @@ This endpoint returns a JSON body like: ] ``` -### /v1/agent/self +### /v1/agent/self This endpoint is used to return configuration of the local agent and member information. @@ -388,7 +388,7 @@ It returns a JSON body like this: } ``` -### /v1/agent/join/\ +### /v1/agent/join/\ 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" @@ -396,7 +396,7 @@ query parameter causes the agent to attempt to join using the WAN pool. The endpoint returns 200 on successful join. -### /v1/agent/force-leave/\ +### /v1/agent/force-leave/\ This endpoint is hit with a GET and is used to instructs 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 @@ -405,7 +405,7 @@ cleaned up. Forcing a node into the left state allows its old entries to be remo The endpoint always returns 200. -### /v1/agent/check/register +### /v1/agent/check/register 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). @@ -439,7 +439,7 @@ the state of the check. The return code is 200 on success. -### /v1/agent/check/deregister/\ +### /v1/agent/check/deregister/\ The deregister endpoint is used to remove a check from the local agent. The CheckID must be passed after the slash. The agent will take care @@ -447,7 +447,7 @@ of deregistering the check with the Catalog. The return code is 200 on success. -### /v1/agent/check/pass/\ +### /v1/agent/check/pass/\ 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", @@ -458,7 +458,7 @@ the status of the check. This should be human readable for operators. The return code is 200 on success. -### /v1/agent/check/warn/\ +### /v1/agent/check/warn/\ 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", @@ -469,7 +469,7 @@ the status of the check. This should be human readable for operators. The return code is 200 on success. -### /v1/agent/check/fail/\ +### /v1/agent/check/fail/\ 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", @@ -480,7 +480,7 @@ the status of the check. This should be human readable for operators. The return code is 200 on success. -### /v1/agent/service/register +### /v1/agent/service/register The register endpoint is used to add a new service to the local agent. There is more documentation on services [here](/docs/agent/services.html). @@ -516,7 +516,7 @@ The created check will be named "service:\". The return code is 200 on success. -### /v1/agent/service/deregister/\ +### /v1/agent/service/deregister/\ The deregister endpoint is used to remove a service from the local agent. The ServiceID must be passed after the slash. The agent will take care @@ -525,25 +525,25 @@ check, that is also deregistered. The return code is 200 on success. -## Catalog +## Catalog The Catalog is the endpoint used to register and deregister nodes, services, and checks. It also provides a number of query endpoints. The following endpoints are supported: -* /v1/catalog/register : Registers a new node, service, or check -* /v1/catalog/deregister : Deregisters a node, service, or check -* /v1/catalog/datacenters : Lists known datacenters -* /v1/catalog/nodes : Lists nodes in a given DC -* /v1/catalog/services : Lists services in a given DC -* /v1/catalog/service/\ : Lists the nodes in a given service -* /v1/catalog/node/\ : Lists the services provided by a node +* [`/v1/catalog/register`](#catalog_register) : Registers a new node, service, or check +* [`/v1/catalog/deregister`](#catalog_deregister) : Deregisters a node, service, or check +* [`/v1/catalog/datacenters`](#catalog_datacenters) : Lists known datacenters +* [`/v1/catalog/nodes`](#catalog_nodes) : Lists nodes in a given DC +* [`/v1/catalog/services`](#catalog_services) : Lists services in a given DC +* [`/v1/catalog/service/\`](#catalog_service) : Lists the nodes in a given service +* [`/v1/catalog/node/\`](#catalog_nodes) : Lists the services provided by a node The last 4 endpoints of the catalog support blocking queries and consistency modes. -### /v1/catalog/register +### /v1/catalog/register The register endpoint is a low level mechanism for directly registering or updating entries in the catalog. It is usually recommended to use @@ -604,7 +604,7 @@ and visa-versa. They can be provided or omitted at will. If the API call succeeds a 200 status code is returned. -### /v1/catalog/deregister +### /v1/catalog/deregister The deregister endpoint is a low level mechanism for direclty removing entries in the catalog. It is usually recommended to use the agent local @@ -646,7 +646,7 @@ service along with its associated health check (if any) is removed. If the API call succeeds a 200 status code is returned. -### /v1/catalog/datacenters +### /v1/catalog/datacenters This endpoint is hit with a GET and is used to return all the datacenters that are known by the Consul server. @@ -661,7 +661,7 @@ This endpoint does not require a cluster leader, and as such will succeed even during an availability outage. It can thus be a simple check to see if any Consul servers are routable. -### /v1/catalog/nodes +### /v1/catalog/nodes This endpoint is hit with a GET and returns the nodes known about in a given DC. By default the datacenter of the agent is queried, @@ -684,7 +684,7 @@ It returns a JSON body like this: This endpoint supports blocking queries and all consistency modes. -### /v1/catalog/services +### /v1/catalog/services This endpoint is hit with a GET and returns the services known about in a given DC. By default the datacenter of the agent is queried, @@ -708,7 +708,7 @@ provides all the known tags for a given service. This endpoint supports blocking queries and all consistency modes. -### /v1/catalog/service/\ +### /v1/catalog/service/\ This endpoint is hit with a GET and returns the nodes providing a service in a given DC. By default the datacenter of the agent is queried, @@ -735,7 +735,7 @@ It returns a JSON body like this: This endpoint supports blocking queries and all consistency modes. -### /v1/catalog/node/\ +### /v1/catalog/node/\ This endpoint is hit with a GET and returns the node provided services. By default the datacenter of the agent is queried, @@ -771,7 +771,7 @@ It returns a JSON body like this: This endpoint supports blocking queries and all consistency modes. -## Health +## Health The Health used to query health related information. It is provided separately from the Catalog, since users may prefer to not use the health checking mechanisms @@ -779,14 +779,14 @@ as they are totally optional. Additionally, some of the query results from the H The following endpoints are supported: -* /v1/health/node/\: Returns the health info of a node -* /v1/health/checks/\: Returns the checks of a service -* /v1/health/service/\: Returns the nodes and health info of a service -* /v1/health/state/\: Returns the checks in a given state +* [`/v1/health/node/\`](#health_node): Returns the health info of a node +* [`/v1/health/checks/\`](#health_checks): Returns the checks of a service +* [`/v1/health/service/\`](#health_service): Returns the nodes and health info of a service +* [`/v1/health/state/\`](#health_state): Returns the checks in a given state All of the health endpoints supports blocking queries and all consistency modes. -### /v1/health/node/\ +### /v1/health/node/\ This endpoint is hit with a GET and returns the node specific checks known. By default the datacenter of the agent is queried, @@ -829,7 +829,7 @@ changed to "critical". This endpoint supports blocking queries and all consistency modes. -### /v1/health/checks/\ +### /v1/health/checks/\ This endpoint is hit with a GET and returns the checks associated with a service in a given datacenter. @@ -856,7 +856,7 @@ It returns a JSON body like this: This endpoint supports blocking queries and all consistency modes. -### /v1/health/service/\ +### /v1/health/service/\ This endpoint is hit with a GET and returns the service nodes providing a given service in a given datacenter. @@ -922,7 +922,7 @@ It returns a JSON body like this: This endpoint supports blocking queries and all consistency modes. -### /v1/health/state/\ +### /v1/health/state/\ This endpoint is hit with a GET and returns the checks in a specific state for a given datacenter. By default the datacenter of the agent is queried, @@ -961,20 +961,20 @@ It returns a JSON body like this: This endpoint supports blocking queries and all consistency modes. -## Session +## Session The Session endpoints are used to create, destroy and query sessions. The following endpoints are supported: -* /v1/session/create: Creates a new session -* /v1/session/destroy/\: Destroys a given session -* /v1/session/info/\: Queries a given session -* /v1/session/node/\: Lists sessions belonging to a node -* /v1/session/list: Lists all the active sessions +* [`/v1/session/create`](#session_create): Creates a new session +* [`/v1/session/destroy/\`](#session_destroy): Destroys a given session +* [`/v1/session/info/\`](#session_info): Queries a given session +* [`/v1/session/node/\`](#session_node): Lists sessions belonging to a node +* [`/v1/session/list`](#session_list): Lists all the active sessions All of the read session endpoints supports blocking queries and all consistency modes. -### /v1/session/create +### /v1/session/create The create endpoint is used to initialize a new session. There is more documentation on sessions [here](/docs/internals/sessions.html). @@ -1020,7 +1020,7 @@ The return code is 200 on success, along with a body like: This is used to provide the ID of the newly created session. -### /v1/session/destroy/\ +### /v1/session/destroy/\ The destroy endpoint is hit with a PUT and destroys the given session. By default the local datacenter is used, but the "?dc=" query parameter @@ -1029,7 +1029,7 @@ be provided after the slash. The return code is 200 on success. -### /v1/session/info/\ +### /v1/session/info/\ This endpoint is hit with a GET and returns the session information by ID within a given datacenter. By default the datacenter of the agent is queried, @@ -1055,7 +1055,7 @@ It returns a JSON body like this: If the session is not found, null is returned instead of a JSON list. This endpoint supports blocking queries and all consistency modes. -### /v1/session/node/\ +### /v1/session/node/\ This endpoint is hit with a GET and returns the active sessions for a given node and datacenter. By default the datacenter of the agent is queried, @@ -1081,7 +1081,7 @@ It returns a JSON body like this: This endpoint supports blocking queries and all consistency modes. -### /v1/session/list +### /v1/session/list This endpoint is hit with a GET and returns the active sessions for a given datacenter. By default the datacenter of the agent is queried, @@ -1106,19 +1106,19 @@ It returns a JSON body like this: This endpoint supports blocking queries and all consistency modes. -## ACL +## ACL The ACL endpoints are used to create, update, destroy and query ACL tokens. The following endpoints are supported: -* /v1/acl/create: Creates a new token with policy -* /v1/acl/update: Update the policy of a token -* /v1/acl/destroy/\: Destroys a given token -* /v1/acl/info/\: Queries the policy of a given token -* /v1/acl/clone/\: Creates a new token by cloning an existing token -* /v1/acl/list: Lists all the active tokens +* [`/v1/acl/create`](#acl_create): Creates a new token with policy +* [`/v1/acl/update`](#acl_update): Update the policy of a token +* [`/v1/acl/destroy/\`](#acl_destroy): Destroys a given token +* [`/v1/acl/info/\`](#acl_info): Queries the policy of a given token +* [`/v1/acl/clone/\`](#acl_clone): Creates a new token by cloning an existing token +* [`/v1/acl/list`](#acl_list): Lists all the active tokens -### /v1/acl/create +### /v1/acl/create The create endpoint is used to make a new token. A token has a name, type, and a set of ACL rules. The name is opaque to Consul, and type @@ -1159,7 +1159,7 @@ The return code is 200 on success, along with a body like: This is used to provide the ID of the newly created ACL token. -### /v1/acl/update +### /v1/acl/update The update endpoint is used to modify the policy for a given ACL token. It is very similar to the create endpoint, however @@ -1189,7 +1189,7 @@ The format of `Rules` is [documented here](/docs/internals/acl.html). The return code is 200 on success. -### /v1/acl/destroy/\ +### /v1/acl/destroy/\ The destroy endpoint is hit with a PUT and destroys the given ACL token. The request is automatically routed to the authoritative ACL datacenter. @@ -1198,7 +1198,7 @@ to the endpoint must be made with a management token. The return code is 200 on success. -### /v1/acl/info/\ +### /v1/acl/info/\ This endpoint is hit with a GET and returns the token information by ID. All requests are routed to the authoritative ACL datacenter @@ -1221,7 +1221,7 @@ It returns a JSON body like this: If the session is not found, null is returned instead of a JSON list. -### /v1/acl/clone/\ +### /v1/acl/clone/\ The clone endpoint is hit with a PUT and returns a token ID that is cloned from an existing token. This allows a token to serve @@ -1239,7 +1239,7 @@ The return code is 200 on success, along with a body like: This is used to provide the ID of the newly created ACL token. -### /v1/acl/list +### /v1/acl/list The list endpoint is hit with a GET and lists all the active ACL tokens. This is a privileged endpoint, and requires a @@ -1261,17 +1261,17 @@ It returns a JSON body like this: ] ``` -## Event +## Event The Event endpoints are used to fire new events and to query the available events. The following endpoints are supported: -* /v1/event/fire/\: Fires a new user event -* /v1/event/list: Lists the most recent events an agent has seen. +* [`/v1/event/fire/\`](#event_fire): Fires a new user event +* [`/v1/event/list`](#event_list): Lists the most recent events an agent has seen. -### /v1/event/fire/\ +### /v1/event/fire/\ The fire endpoint is used to trigger a new user event. A user event needs a name, and optionally takes a number of parameters. @@ -1305,7 +1305,7 @@ The return code is 200 on success, along with a body like: This is used to provide the ID of the newly fired event. -### /v1/event/list +### /v1/event/list This endpoint is hit with a GET and returns the most recent events known by the agent. As a consequence of how the @@ -1357,7 +1357,7 @@ It returns a JSON body like this: ] ``` -## Status +## Status The Status endpoints are used to get information about the status of the Consul cluster. This are generally very low level, and not really @@ -1365,10 +1365,10 @@ useful for clients. The following endpoints are supported: -* /v1/status/leader : Returns the current Raft leader -* /v1/status/peers : Returns the current Raft peer set +* [`/v1/status/leader`](#status_leader) : Returns the current Raft leader +* [`/v1/status/peers`](#status_peers) : Returns the current Raft peer set -### /v1/status/leader +### /v1/status/leader This endpoint is used to get the Raft leader for the datacenter the agent is running in. It returns only an address like: @@ -1377,7 +1377,7 @@ the agent is running in. It returns only an address like: "10.1.10.12:8300" ``` -### /v1/status/peers +### /v1/status/peers This endpoint is used to get the Raft peers for the datacenter the agent is running in. It returns a list of addresses like: @@ -1389,3 +1389,12 @@ the agent is running in. It returns a list of addresses like: "10.1.10.10:8300" ] ``` + +[kv]: #kv +[agent]: #agent +[catalog]: #catalog +[health]: #health +[session]: #session +[acl]: #acl +[event]: #event +[status]: #status