diff --git a/website/source/docs/agent/http/session.html.markdown b/website/source/docs/agent/http/session.html.markdown index f37fd34902..655c457930 100644 --- a/website/source/docs/agent/http/session.html.markdown +++ b/website/source/docs/agent/http/session.html.markdown @@ -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_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 -* [`/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. ### /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. - ### /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 -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. ### /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, -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. ### /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, -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. ### /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. ### /v1/session/renew/\ 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.