luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

website: Update session API documentation

This commit is contained in:
Armon Dadgar 2015-01-07 15:19:21 -08:00
parent 7ecd015fc0
commit b435a0c842
1 changed files with 48 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -975,6 +975,7 @@ The following endpoints are supported:
* [`/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
All of the read session endpoints supports blocking queries and all consistency modes.
@ -998,7 +999,9 @@ body must look like:
"LockDelay": "15s",
"Name": "my-service-lock",
"Node": "foobar",
"Checks": ["a", "b", "c"]
"Checks": ["a", "b", "c"],
"Behavior": "release",
"TTL": "0s"
}
```
@ -1010,10 +1013,21 @@ nanosecond granularity.
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. Lastly, the `Checks` field is used to provide
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.
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
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.
The return code is 200 on success, along with a body like:
```javascript
@ -1110,6 +1124,38 @@ It returns a JSON body like this:
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.
The return code is 200 on success and a JSON body like this:
```javascript
[
{
"LockDelay": 1.5e+10,
"Checks": [
"serfHealth"
],
"Node": "foobar",
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
"CreateIndex": 1086449
"Behavior": "release",
"TTL": "15s"
}
]
```
The response body includes the current session.
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.
## <a name="acl"></a> ACL
The ACL endpoints are used to create, update, destroy and query ACL tokens.