status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #427 from blalor/agent_http_links 

website: Improve navigability of agent HTTP API categories
This commit is contained in:
Armon Dadgar 2014-10-23 16:46:58 -07:00
parent 805a9f7ec2 914db50a52
commit c7d5330471
1 changed files with 103 additions and 94 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

197
website/source/docs/agent/http.html.markdown
View File

@ -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
## <a name="kv"></a> 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
## <a name="agent"></a> 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/\<address\> : Trigger local agent to join a node
* /v1/agent/force-leave/\<node\>: Force remove node
* /v1/agent/check/register : Registers a new local check
* /v1/agent/check/deregister/\<checkID\> : Deregister a local check
* /v1/agent/check/pass/\<checkID\> : Mark a local test as passing
* /v1/agent/check/warn/\<checkID\> : Mark a local test as warning
* /v1/agent/check/fail/\<checkID\> : Mark a local test as critical
* /v1/agent/service/register : Registers a new local service
* /v1/agent/service/deregister/\<serviceID\> : 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/\<address\>`](#agent_join) : Trigger local agent to join a node
* [`/v1/agent/force-leave/\<node\`](#agent_force_leave)>: Force remove 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/pass/\<checkID\>`](#agent_check_pass) : Mark a local test as passing
* [`/v1/agent/check/warn/\<checkID\>`](#agent_check_warn) : Mark a local test as warning
* [`/v1/agent/check/fail/\<checkID\>`](#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/\<serviceID\>`](#agent_service_deregister) : Deregister a local service
### /v1/agent/checks
### <a name="agent_checks"></a> /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
### <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,
@ -285,7 +285,7 @@ This endpoint is hit with a GET and returns a JSON body like this:
}
```
### /v1/agent/members
### <a name="agent_members"></a> /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
### <a name="agent_self"></a> /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/\<address\>
### <a name="agent_join"></a> /v1/agent/join/\<address\>
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/\<node\>
### <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.
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
### <a name="agent_check_register"></a> /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/\<checkId\>
### <a name="agent_check_deregister"></a> /v1/agent/check/deregister/\<checkId\>
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/\<checkId\>
### <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",
@ -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/\<checkId\>
### <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",
@ -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/\<checkId\>
### <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",
@ -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
### <a name="agent_service_register"></a> /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:\<ServiceId\>".
The return code is 200 on success.
### /v1/agent/service/deregister/\<serviceId\>
### <a name="agent_service_deregister"></a> /v1/agent/service/deregister/\<serviceId\>
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
## <a name="catalog"></a> 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/\<service\> : Lists the nodes in a given service
* /v1/catalog/node/\<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/\<service\>`](#catalog_service) : Lists the nodes in a given service
* [`/v1/catalog/node/\<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
### <a name="catalog_register"></a> /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
### <a name="catalog_deregister"></a> /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
### <a name="catalog_datacenters"></a> /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
### <a name="catalog_nodes"></a> /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
### <a name="catalog_services"></a> /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/\<service\>
### <a name="catalog_service"></a> /v1/catalog/service/\<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/\<node\>
### <a name="catalog_node"></a> /v1/catalog/node/\<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
## <a name="health"></a> 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/\<node\>: Returns the health info of a node
* /v1/health/checks/\<service\>: Returns the checks of a service
* /v1/health/service/\<service\>: Returns the nodes and health info of a service
* /v1/health/state/\<state\>: Returns the checks in a given state
* [`/v1/health/node/\<node\>`](#health_node): Returns the health info of a node
* [`/v1/health/checks/\<service\>`](#health_checks): Returns the checks of a service
* [`/v1/health/service/\<service\>`](#health_service): Returns the nodes and health info of a service
* [`/v1/health/state/\<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/\<node\>
### <a name="health_node"></a> /v1/health/node/\<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/\<service\>
### <a name="health_checks"></a> /v1/health/checks/\<service\>
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/\<service\>
### <a name="health_service"></a> /v1/health/service/\<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/\<state\>
### <a name="health_state"></a> /v1/health/state/\<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
## <a name="session"></a> 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/\<session\>: Destroys a given session
* /v1/session/info/\<session\>: Queries a given session
* /v1/session/node/\<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\>`](#session_destroy): Destroys a given session
* [`/v1/session/info/\<session\>`](#session_info): Queries a given session
* [`/v1/session/node/\<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
### <a name="session_create"></a> /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/\<session\>
### <a name="session_destroy"></a> /v1/session/destroy/\<session\>
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/\<session\>
### <a name="session_info"></a> /v1/session/info/\<session\>
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/\<node\>
### <a name="session_node"></a> /v1/session/node/\<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
### <a name="session_list"></a> /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
## <a name="acl"></a> 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/\<id\>: Destroys a given token
* /v1/acl/info/\<id\>: Queries the policy of a given token
* /v1/acl/clone/\<id\>: 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/\<id\>`](#acl_destroy): Destroys a given token
* [`/v1/acl/info/\<id\>`](#acl_info): Queries the policy of a given token
* [`/v1/acl/clone/\<id\>`](#acl_clone): Creates a new token by cloning an existing token
* [`/v1/acl/list`](#acl_list): Lists all the active tokens
### /v1/acl/create
### <a name="acl_create"></a> /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
### <a name="acl_update"></a> /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/\<id\>
### <a name="acl_destroy"></a> /v1/acl/destroy/\<id\>
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/\<id\>
### <a name="acl_info"></a> /v1/acl/info/\<id\>
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/\<id\>
### <a name="acl_clone"></a> /v1/acl/clone/\<id\>
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
### <a name="acl_list"></a> /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
## <a name="event"></a> Event
The Event endpoints are used to fire new events and to query the available
events.
The following endpoints are supported:
* /v1/event/fire/\<name\>: Fires a new user event
* /v1/event/list: Lists the most recent events an agent has seen.
* [`/v1/event/fire/\<name\>`](#event_fire): Fires a new user event
* [`/v1/event/list`](#event_list): Lists the most recent events an agent has seen.
### /v1/event/fire/\<name\>
### <a name="event_fire"></a> /v1/event/fire/\<name\>
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
### <a name="event_list"></a> /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
## <a name="status"></a> 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
### <a name="status_leader"></a> /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
### <a name="status_peers"></a> /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