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

Website: cleanup for docs/agent/http/session.

This commit is contained in:
Ryan Breen 2015-02-12 14:50:54 -05:00
parent a82bbb6561
commit d2bc6f156d
1 changed files with 51 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
website/source/docs/agent/http/session.html.markdown
View File

@ -3,34 +3,28 @@ layout: "docs"
page_title: "Sessions (HTTP)" page_title: "Sessions (HTTP)"
sidebar_current: "docs-agent-http-sessions" sidebar_current: "docs-agent-http-sessions"
description: > 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 # 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: The following endpoints are supported:
* [`/v1/session/create`](#session_create): Creates a new session * [`/v1/session/create`](#session_create): Creates a new session
* [`/v1/session/destroy/<session>`](#session_destroy): Destroys a given session * [`/v1/session/destroy/<session>`](#session_destroy): Destroys a given session
* [`/v1/session/info/<session>`](#session_info): Queries 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/node/<node>`](#session_node): Lists sessions belonging to a node
* [`/v1/session/list`](#session_list): Lists all the active sessions * [`/v1/session/list`](#session_list): Lists all active sessions
* [`/v1/session/renew`](#session_renew): Renew a TTL based session * [`/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 ### <a name="session_create"></a> /v1/session/create
The create endpoint is used to initialize a new session. The create endpoint is used to initialize a new session.
There is more documentation on sessions [here](/docs/internals/sessions.html). There is more documentation on sessions [here](/docs/internals/sessions.html).
Sessions must be associated with a node, and optionally any number of checks. Sessions must be associated with a node and may be associated with 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.
The create endpoint expects a JSON request body to be PUT. The request The create endpoint expects a JSON request body to be PUT. The request
body must look like: body must look like:
@ -47,29 +41,38 @@ body must look like:
``` ```
None of the fields are mandatory, and in fact no body needs to be PUT 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 if the defaults are to be used.
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.
The `Node` field must refer to a node that is already registered. By default, By default, the agent's local datacenter is used; another datacenter
the agent will use it's own name. The `Name` field can be used to provide a human can be specified using the "?dc=" query parameter. However, it is not recommended
readable name for the Session. The `Checks` field is used to provide to use cross-datacenter sessions.
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.
The `Behavior` field can be set to either "release" or "delete". This controls `LockDelay` field can be specified as a duration string using a "s" suffix for
the behavior when a session is invalidated. By default this is "release", and seconds. The default is 15s. This value can also be a numeric value. Small values are
this causes any locks that are held to be released. Changing this to "delete" treated as seconds while larger values are assumed to be nanoseconds.
causes any locks that are held to be deleted. This is useful to create ephemeral <QUESTION: I don't see anywhere in the code to substantiate this. If this is true, how do we define small and large values? We need to give people some boundaries. QUESTION>
`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. key/value entries.
The `TTL` field is a duration string, and like `LockDelay` it can use "s" as 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. 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 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 ```javascript
{ {
@ -77,23 +80,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\> ### <a name="session_destroy"></a> /v1/session/destroy/\<session\>
The destroy endpoint is hit with a PUT and destroys the given 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 By default, the local datacenter is used, but the "?dc=" query parameter
can be used to specify the datacenter. The session being destroyed must can be used to specify the datacenter.
be provided after the slash.
The session being destroyed must be provided on the path.
The return code is 200 on success. The return code is 200 on success.
### <a name="session_info"></a> /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 This endpoint is hit with a GET and returns the requested session information
by ID within a given datacenter. By default the datacenter of the agent is queried, within a given datacenter. By default, the datacenter of the agent is queried;
however the dc can be provided using the "?dc=" query parameter. however, the dc can be provided using the "?dc=" query parameter.
The session being queried must be provided after the slash. The session being queried must be provided on the path.
It returns a JSON body like this: It returns a JSON body like this:
@ -117,9 +119,10 @@ This endpoint supports blocking queries and all consistency modes.
### <a name="session_node"></a> /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 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, 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. however, the dc can be provided using the "?dc=" query parameter.
The node being queried must be provided after the slash.
The node being queried must be provided on the path.
It returns a JSON body like this: It returns a JSON body like this:
@ -143,8 +146,8 @@ This endpoint supports blocking queries and all consistency modes.
### <a name="session_list"></a> /v1/session/list ### <a name="session_list"></a> /v1/session/list
This endpoint is hit with a GET and returns the active sessions 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, for a given datacenter. By default, the datacenter of the agent is queried;
however the dc can be provided using the "?dc=" query parameter. however, the dc can be provided using the "?dc=" query parameter.
It returns a JSON body like this: It returns a JSON body like this:
@ -168,10 +171,11 @@ This endpoint supports blocking queries and all consistency modes.
### <a name="session_renew"></a> /v1/session/renew/\<session\> ### <a name="session_renew"></a> /v1/session/renew/\<session\>
The renew endpoint is hit with a PUT and renews the given 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 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=" 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 query parameter can be used to specify the datacenter.
must be provided after the slash.
The session being renewed must be provided on the path.
The return code is 200 on success and a JSON body like this: The return code is 200 on success and a JSON body like this:
@ -192,6 +196,7 @@ The return code is 200 on success and a JSON body like this:
``` ```
The response body includes the current session. 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 This indicates the server is under high load and is requesting clients renew less
often. often.