Merge pull request #695 from ryanbreen/session
Website: cleanup for docs/agent/http/session
This commit is contained in:
Armon Dadgar
commit
65bdd83187
|
|
@ -3,34 +3,28 @@ layout: "docs"
|
|||
page_title: "Sessions (HTTP)"
|
||||
sidebar_current: "docs-agent-http-sessions"
|
||||
description: >
|
||||
The Session endpoints are used to create, destroy and query sessions.
|
||||
The Session endpoints are used to create, destroy, and query sessions.
|
||||
---
|
||||
|
||||
# Session HTTP Endpoint
|
||||
|
||||
The Session endpoints are used to create, destroy and query sessions.
|
||||
The Session endpoints are used to create, destroy, and query sessions.
|
||||
The following endpoints are supported:
|
||||
|
||||
* [`/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
|
||||
* [`/v1/session/renew`](#session_renew): Renew a TTL based session
|
||||
* [`/v1/session/list`](#session_list): Lists all active sessions
|
||||
* [`/v1/session/renew`](#session_renew): Renews a TTL-based session
|
||||
|
||||
All of the read session endpoints supports blocking queries and all consistency modes.
|
||||
All of the read session endpoints support blocking queries and all consistency modes.
|
||||
|
||||
### <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).
|
||||
Sessions must be associated with a node, and optionally any number of checks.
|
||||
By default, the agent uses it's own node name, and provides the "serfHealth"
|
||||
check, along with a 15 second lock delay.
|
||||
|
||||
By default, the agent's local datacenter is used, but another datacenter
|
||||
can be specified using the "?dc=" query parameter. It is not recommended
|
||||
to use cross-region sessions.
|
||||
Sessions must be associated with a node and may be associated with any number of checks.
|
||||
|
||||
The create endpoint expects a JSON request body to be PUT. The request
|
||||
body must look like:
|
||||
|
|
@ -47,29 +41,36 @@ body must look like:
|
|||
```
|
||||
|
||||
None of the fields are mandatory, and in fact no body needs to be PUT
|
||||
if the defaults are to be used. The `LockDelay` field can be specified
|
||||
as a duration string using a "s" suffix for seconds. It can also be a numeric
|
||||
value. Small values are treated as seconds, and otherwise it is provided with
|
||||
nanosecond granularity.
|
||||
if the defaults are to be used.
|
||||
|
||||
The `Node` field must refer to a node that is already registered. By default,
|
||||
the agent will use it's own name. The `Name` field can be used to provide a human
|
||||
readable name for the Session. The `Checks` field is used to provide
|
||||
a list of associated health checks. By default the "serfHealth" check is provided.
|
||||
It is highly recommended that if you override this list, you include that check.
|
||||
By default, the agent's local datacenter is used; another datacenter
|
||||
can be specified using the "?dc=" query parameter. However, it is not recommended
|
||||
to use cross-datacenter sessions.
|
||||
|
||||
The `Behavior` field can be set to either "release" or "delete". This controls
|
||||
the behavior when a session is invalidated. By default this is "release", and
|
||||
this causes any locks that are held to be released. Changing this to "delete"
|
||||
causes any locks that are held to be deleted. This is useful to create ephemeral
|
||||
`LockDelay` can be specified as a duration string using a "s" suffix for
|
||||
seconds. The default is 15s.
|
||||
|
||||
`Node` must refer to a node that is already registered, if specified. By default,
|
||||
the agent's own node name is used.
|
||||
|
||||
`Name` can be used to provide a human-readable name for the Session.
|
||||
|
||||
`Checks` is used to provide a list of associated health checks. It is highly recommended
|
||||
that, if you override this list, you include the default "serfHealthCheck".
|
||||
|
||||
`Behavior` can be set to either `release` or `delete`. This controls
|
||||
the behavior when a session is invalidated. By default, this is `release`,
|
||||
causing any locks that are held to be released. Changing this to `delete`
|
||||
causes any locks that are held to be deleted. `delete` is useful for creating ephemeral
|
||||
key/value entries.
|
||||
|
||||
The `TTL` field is a duration string, and like `LockDelay` it can use "s" as
|
||||
a suffix for seconds. If specified, it must be between 10s and 3600s currently.
|
||||
When provided, the session is invalidated if it is not renewed before the TTL
|
||||
expires. See the [session internals page](/docs/internals/session.html) for more documentation.
|
||||
expires. See the [session internals page](/docs/internals/session.html) for more
|
||||
documentation of this feature.
|
||||
|
||||
The return code is 200 on success, along with a body like:
|
||||
The return code is 200 on success and returns the ID of the created session:
|
||||
|
||||
```javascript
|
||||
{
|
||||
|
|
@ -77,23 +78,22 @@ The return code is 200 on success, along with a body like:
|
|||
}
|
||||
```
|
||||
|
||||
This is used to provide the ID of the newly created 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
|
||||
can be used to specify the datacenter. The session being destroyed must
|
||||
be provided after the slash.
|
||||
By default, the local datacenter is used, but the "?dc=" query parameter
|
||||
can be used to specify the datacenter.
|
||||
|
||||
The session being destroyed must be provided on the path.
|
||||
|
||||
The return code is 200 on success.
|
||||
|
||||
### <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,
|
||||
however the dc can be provided using the "?dc=" query parameter.
|
||||
The session being queried must be provided after the slash.
|
||||
This endpoint is hit with a GET and returns the requested session information
|
||||
within a given datacenter. By default, the datacenter of the agent is queried;
|
||||
however, the dc can be provided using the "?dc=" query parameter.
|
||||
The session being queried must be provided on the path.
|
||||
|
||||
It returns a JSON body like this:
|
||||
|
||||
|
|
@ -117,9 +117,10 @@ This endpoint supports blocking queries and all consistency modes.
|
|||
### <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,
|
||||
however the dc can be provided using the "?dc=" query parameter.
|
||||
The node being queried must be provided after the slash.
|
||||
for a given node and datacenter. By default, the datacenter of the agent is queried;
|
||||
however, the dc can be provided using the "?dc=" query parameter.
|
||||
|
||||
The node being queried must be provided on the path.
|
||||
|
||||
It returns a JSON body like this:
|
||||
|
||||
|
|
@ -143,8 +144,8 @@ This endpoint supports blocking queries and all consistency modes.
|
|||
### <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,
|
||||
however the dc can be provided using the "?dc=" query parameter.
|
||||
for a given datacenter. By default, the datacenter of the agent is queried;
|
||||
however, the dc can be provided using the "?dc=" query parameter.
|
||||
|
||||
It returns a JSON body like this:
|
||||
|
||||
|
|
@ -168,12 +169,13 @@ This endpoint supports blocking queries and all consistency modes.
|
|||
### <a name="session_renew"></a> /v1/session/renew/\<session\>
|
||||
|
||||
The renew endpoint is hit with a PUT and renews the given session.
|
||||
This is used with sessions that have a TTL set, and it extends the
|
||||
expiration by the TTL. By default the local datacenter is used, but the "?dc="
|
||||
query parameter can be used to specify the datacenter. The session being renewed
|
||||
must be provided after the slash.
|
||||
This is used with sessions that have a TTL, and it extends the
|
||||
expiration by the TTL. By default, the local datacenter is used, but the "?dc="
|
||||
query parameter can be used to specify the datacenter.
|
||||
|
||||
The return code is 200 on success and a JSON body like this:
|
||||
The session being renewed must be provided on the path.
|
||||
|
||||
The return code is 200 on success. The response JSON body looks like this:
|
||||
|
||||
```javascript
|
||||
[
|
||||
|
|
@ -192,6 +194,7 @@ The return code is 200 on success and a JSON body like this:
|
|||
```
|
||||
|
||||
The response body includes the current session.
|
||||
Consul MAY return a TTL value higher than the one specified during session creation.
|
||||
|
||||
Note: Consul MAY return a TTL value higher than the one specified during session creation.
|
||||
This indicates the server is under high load and is requesting clients renew less
|
||||
often.
|
||||
|
|
|
|||
Loading…
Reference in New Issue