status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity
consul/website/content/api-docs/session.mdx

406 lines
13 KiB
Plaintext
Raw Normal View History

Update API docs
2017-04-04 16:33:22 +00:00
---
layout: api
page_title: Session - HTTP API
intro and api navigation converted
2020-04-07 18:55:19 +00:00
description: 'The /session endpoints create, destroy, and query sessions in Consul.'
Update API docs
2017-04-04 16:33:22 +00:00
---
# Session HTTP Endpoint
OSS Modifications necessary for sessions namespacing
2019-11-25 17:07:04 +00:00
The `/session` endpoints create, destroy, and query sessions in Consul.
Update API docs
2017-04-04 16:33:22 +00:00
## Create Session
This endpoint initializes a new session. Sessions must be associated with a
node and may be associated with any number of checks.
initial
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ----------------- | ------------------ |
| `PUT` | `/session/create` | `application/json` |
Update API docs
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
replace internal .html link extensions
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
remove internal /index.html
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
Update API docs
2017-04-04 16:33:22 +00:00
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | --------------- |
| `NO` | `none` | `none` | `session:write` |
Update API docs
2017-04-04 16:33:22 +00:00
### Parameters
Add callouts to Enterprise features (#7548) Label all enterprise-related content with Enterprise badge/callout. Resolves #6887 Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com>
2020-04-23 22:13:18 +00:00
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
Revert "Remove docs refs to NS inference from ACL token" (#6976) This reverts commit 3a8426de9c76e7d8dd2728e4ae78bc4e5e18626a. # Conflicts: # command/flags/http.go # website/source/api/acl/binding-rules.html.md # website/source/api/acl/policies.html.md # website/source/api/acl/roles.html.md # website/source/api/acl/tokens.html.md # website/source/api/kv.html.md # website/source/api/session.html.md # website/source/docs/commands/_http_api_namespace_options.html.md
2019-12-20 16:52:50 +00:00
If not provided, the namespace will be inferred from the request's ACL token,
or will default to the `default` namespace. This is specified as part of the
URL as a query parameter. Added in Consul 1.7.0.
OSS Modifications necessary for sessions namespacing
2019-11-25 17:07:04 +00:00
Update API docs
2017-04-04 16:33:22 +00:00
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter. Using this across datacenters is not recommended.
OSS Modifications necessary for sessions namespacing
2019-11-25 17:07:04 +00:00
- `LockDelay` `(string: "15s")` - Specifies the duration for the lock delay. This
must be greater than `0`.
Update API docs
2017-04-04 16:33:22 +00:00
- `Node` `(string: "<agent>")` - Specifies the name of the node. This must refer
to a node that is already registered.
- `Name` `(string: "")` - Specifies a human-readable name for the session.
docs: Update responses for /v1/session/ endpoints post 1.7 Update output for /v1/session/ endpoints to match output post Consul 1.7.0. Documents new `NodeChecks` and `ServiceChecks` parameters which were added in that release. Resolves #7341, resolves #10095
2021-07-20 06:52:21 +00:00
- `Checks` `(array<string>: nil)` - Specifies a list of node health
website: clarify format of check IDs for sessions (#5036) * website: clarify format of check IDs for sessions * Update website/source/api/session.html.md Co-Authored-By: pearkes <jackpearkes@gmail.com>
2018-12-11 17:00:52 +00:00
check IDs (commonly `CheckID` in API responses). It is highly recommended that,
if you override this list, you include the default `serfHealth`.
docs: Update responses for /v1/session/ endpoints post 1.7 Update output for /v1/session/ endpoints to match output post Consul 1.7.0. Documents new `NodeChecks` and `ServiceChecks` parameters which were added in that release. Resolves #7341, resolves #10095
2021-07-20 06:52:21 +00:00
Deprecated in Consul 1.7.0 and replaced by `NodeChecks`. This field will be
omitted from the API response in Consul 1.7+ if `serfHealth` is the only defined check.
- `NodeChecks` `(array<string>: nil)` - Specifies a list of node health
check IDs (commonly `CheckID` in API responses). It is highly recommended that,
if you override this list, you include the default `serfHealth`. Added in
Consul 1.7.0.
- `ServiceChecks` `(array<string>: nil)` - Specifies a list of service health
check IDs (commonly `CheckID` in API responses). Added in Consul 1.7.0.
Update API docs
2017-04-04 16:33:22 +00:00
- `Behavior` `(string: "release")` - Controls the behavior to take when a
session is invalidated. Valid values are:
- `release` - causes any locks that are held to be released
fixed typo
2017-04-26 08:09:02 +00:00
- `delete` - causes any locks that are held to be deleted
Update API docs
2017-04-04 16:33:22 +00:00
#8059 Improve Clarity on TTL docs (#8141)
2020-06-18 17:53:43 +00:00
- `TTL` `(string: "")` - Specifies the duration of a session (between 10s and
Update API docs
2017-04-04 16:33:22 +00:00
86400s). If provided, the session is invalidated if it is not renewed before
the TTL expires. The lowest practical TTL should be used to keep the number of
Minor Session / Lock Related Documentation Fixes (#5037) * website: specify value of acquire/release params for kv * website: clarify leader election usage in TTL docs * website: document minimal value of lockdelay I believe it uses the default when parsing 0 as it views that as an empty parameter in this case.
2019-04-03 15:54:21 +00:00
managed sessions low. When locks are forcibly expired, such as when following
Refactor api-docs links to learn (#8488)
2020-08-17 16:20:02 +00:00
the [leader election pattern](https://learn.hashicorp.com/tutorials/consul/application-leader-elections) in an application,
Minor Session / Lock Related Documentation Fixes (#5037) * website: specify value of acquire/release params for kv * website: clarify leader election usage in TTL docs * website: document minimal value of lockdelay I believe it uses the default when parsing 0 as it views that as an empty parameter in this case.
2019-04-03 15:54:21 +00:00
sessions may not be reaped for up to double this TTL, so long TTL
#8059 Improve Clarity on TTL docs (#8141)
2020-06-18 17:53:43 +00:00
values (> 1 hour) should be avoided. Valid time units include "s", "m" and "h".
Update API docs
2017-04-04 16:33:22 +00:00
### Sample Payload
```json
{
"LockDelay": "15s",
"Name": "my-service-lock",
"Node": "foobar",
"Checks": ["a", "b", "c"],
"Behavior": "release",
"TTL": "30s"
}
```
### Sample Request
update dependencies
2020-05-19 18:32:38 +00:00
```shell-session
Update API docs
2017-04-04 16:33:22 +00:00
$ curl \
--request PUT \
--data @payload.json \
website: use 127.0.0.1 instead of consul.rocks (#4523) By default, the Consul agent listens on the local interface at port 8500 for API requests. This change makes the API examples using `curl` copy-pasteable for this default configuration.
2018-08-28 16:07:15 +00:00
http://127.0.0.1:8500/v1/session/create
Update API docs
2017-04-04 16:33:22 +00:00
```
### Sample Response
docs: Update responses for /v1/session/ endpoints post 1.7 Update output for /v1/session/ endpoints to match output post Consul 1.7.0. Documents new `NodeChecks` and `ServiceChecks` parameters which were added in that release. Resolves #7341, resolves #10095
2021-07-20 06:52:21 +00:00
```json
Update API docs
2017-04-04 16:33:22 +00:00
{
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
}
```
- `ID` - the ID of the created session
## Delete Session
This endpoint destroys the session with the given name. If the session UUID is
malformed, an error is returned. If the session UUID does not exist or already
expired, a 200 is still returned (the operation is idempotent).
initial
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| :----- | :----------------------- | ------------------ |
| `PUT` | `/session/destroy/:uuid` | `application/json` |
Update API docs
2017-04-04 16:33:22 +00:00
Even though the Content-Type is `application/json`, the response is
either a literal `true` or `false`, indicating of whether the destroy was
successful.
The table below shows this endpoint's support for
replace internal .html link extensions
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
remove internal /index.html
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
Update API docs
2017-04-04 16:33:22 +00:00
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | --------------- |
| `NO` | `none` | `none` | `session:write` |
Update API docs
2017-04-04 16:33:22 +00:00
### Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the session to destroy.
This is required and is specified as part of the URL path.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter. Using this across datacenters is not recommended.
initial
2020-04-06 20:27:35 +00:00
Add callouts to Enterprise features (#7548) Label all enterprise-related content with Enterprise badge/callout. Resolves #6887 Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com>
2020-04-23 22:13:18 +00:00
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
Revert "Remove docs refs to NS inference from ACL token" (#6976) This reverts commit 3a8426de9c76e7d8dd2728e4ae78bc4e5e18626a. # Conflicts: # command/flags/http.go # website/source/api/acl/binding-rules.html.md # website/source/api/acl/policies.html.md # website/source/api/acl/roles.html.md # website/source/api/acl/tokens.html.md # website/source/api/kv.html.md # website/source/api/session.html.md # website/source/docs/commands/_http_api_namespace_options.html.md
2019-12-20 16:52:50 +00:00
If not provided, the namespace will be inferred from the request's ACL token,
or will default to the `default` namespace. This is specified as part of the
URL as a query parameter. Added in Consul 1.7.0.
Update API docs
2017-04-04 16:33:22 +00:00
### Sample Request
update dependencies
2020-05-19 18:32:38 +00:00
```shell-session
Update API docs
2017-04-04 16:33:22 +00:00
$ curl \
fix invalid curl request (#5972)
2019-06-20 14:48:56 +00:00
--request PUT \
website: use 127.0.0.1 instead of consul.rocks (#4523) By default, the Consul agent listens on the local interface at port 8500 for API requests. This change makes the API examples using `curl` copy-pasteable for this default configuration.
2018-08-28 16:07:15 +00:00
http://127.0.0.1:8500/v1/session/destroy/adf4238a-882b-9ddc-4a9d-5b6758e4159e
Update API docs
2017-04-04 16:33:22 +00:00
```
### Sample Response
```json
true
```
## Read Session
This endpoint returns the requested session information.
initial
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| :----- | :-------------------- | ------------------ |
| `GET` | `/session/info/:uuid` | `application/json` |
Update API docs
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
replace internal .html link extensions
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
remove internal /index.html
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
Update API docs
2017-04-04 16:33:22 +00:00
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | -------------- |
| `YES` | `all` | `none` | `session:read` |
Update API docs
2017-04-04 16:33:22 +00:00
### Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the session to read.
This is required and is specified as part of the URL path.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter. Using this across datacenters is not recommended.
initial
2020-04-06 20:27:35 +00:00
Add callouts to Enterprise features (#7548) Label all enterprise-related content with Enterprise badge/callout. Resolves #6887 Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com>
2020-04-23 22:13:18 +00:00
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
Revert "Remove docs refs to NS inference from ACL token" (#6976) This reverts commit 3a8426de9c76e7d8dd2728e4ae78bc4e5e18626a. # Conflicts: # command/flags/http.go # website/source/api/acl/binding-rules.html.md # website/source/api/acl/policies.html.md # website/source/api/acl/roles.html.md # website/source/api/acl/tokens.html.md # website/source/api/kv.html.md # website/source/api/session.html.md # website/source/docs/commands/_http_api_namespace_options.html.md
2019-12-20 16:52:50 +00:00
If not provided, the namespace will be inferred from the request's ACL token,
or will default to the `default` namespace. This is specified as part of the
URL as a query parameter. Added in Consul 1.7.0.
Update API docs
2017-04-04 16:33:22 +00:00
### Sample Request
update dependencies
2020-05-19 18:32:38 +00:00
```shell-session
Update API docs
2017-04-04 16:33:22 +00:00
$ curl \
website: use 127.0.0.1 instead of consul.rocks (#4523) By default, the Consul agent listens on the local interface at port 8500 for API requests. This change makes the API examples using `curl` copy-pasteable for this default configuration.
2018-08-28 16:07:15 +00:00
http://127.0.0.1:8500/v1/session/info/adf4238a-882b-9ddc-4a9d-5b6758e4159e
Update API docs
2017-04-04 16:33:22 +00:00
```
### Sample Response
```json
[
{
website: update the response json fields for sessions (#4604) Updated the response json with the true response from Consul 1.2.2
2018-10-24 14:33:25 +00:00
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
"Name": "test-session",
initial
2020-04-06 20:27:35 +00:00
"Node": "raja-laptop-02",
docs: Update responses for /v1/session/ endpoints post 1.7 Update output for /v1/session/ endpoints to match output post Consul 1.7.0. Documents new `NodeChecks` and `ServiceChecks` parameters which were added in that release. Resolves #7341, resolves #10095
2021-07-20 06:52:21 +00:00
"LockDelay": 15000000000,
website: update the response json fields for sessions (#4604) Updated the response json with the true response from Consul 1.2.2
2018-10-24 14:33:25 +00:00
"Behavior": "release",
"TTL": "30s",
docs: Update responses for /v1/session/ endpoints post 1.7 Update output for /v1/session/ endpoints to match output post Consul 1.7.0. Documents new `NodeChecks` and `ServiceChecks` parameters which were added in that release. Resolves #7341, resolves #10095
2021-07-20 06:52:21 +00:00
"NodeChecks": [
"serfHealth"
],
"ServiceChecks": null,
website: update the response json fields for sessions (#4604) Updated the response json with the true response from Consul 1.2.2
2018-10-24 14:33:25 +00:00
"CreateIndex": 1086449,
"ModifyIndex": 1086449
Update API docs
2017-04-04 16:33:22 +00:00
}
]
```
docs: changed the return value from null to empty JSON list, when a session does not exist (#7232)
2020-02-11 10:03:28 +00:00
If the session does not exist, an empty JSON list `[]` is returned.
Update API docs
2017-04-04 16:33:22 +00:00
## List Sessions for Node
This endpoint returns the active sessions for a given node.
initial
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| :----- | :-------------------- | ------------------ |
| `GET` | `/session/node/:node` | `application/json` |
Update API docs
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
replace internal .html link extensions
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
remove internal /index.html
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
Update API docs
2017-04-04 16:33:22 +00:00
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | -------------- |
| `YES` | `all` | `none` | `session:read` |
Update API docs
2017-04-04 16:33:22 +00:00
### Parameters
- `node` `(string: <required>)` - Specifies the name or ID of the node to query.
This is required and is specified as part of the URL path.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter. Using this across datacenters is not recommended.
initial
2020-04-06 20:27:35 +00:00
Add callouts to Enterprise features (#7548) Label all enterprise-related content with Enterprise badge/callout. Resolves #6887 Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com>
2020-04-23 22:13:18 +00:00
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
Revert "Remove docs refs to NS inference from ACL token" (#6976) This reverts commit 3a8426de9c76e7d8dd2728e4ae78bc4e5e18626a. # Conflicts: # command/flags/http.go # website/source/api/acl/binding-rules.html.md # website/source/api/acl/policies.html.md # website/source/api/acl/roles.html.md # website/source/api/acl/tokens.html.md # website/source/api/kv.html.md # website/source/api/session.html.md # website/source/docs/commands/_http_api_namespace_options.html.md
2019-12-20 16:52:50 +00:00
If not provided, the namespace will be inferred from the request's ACL token,
or will default to the `default` namespace. This is specified as part of the
URL as a query parameter
initial
2020-04-06 20:27:35 +00:00
The namespace may be specified as '\*' and then results will be returned for all namespaces.
Fix typos and add expand wildcard ns docs
2019-12-10 21:04:24 +00:00
Added in Consul 1.7.0.
Update API docs
2017-04-04 16:33:22 +00:00
### Sample Request
update dependencies
2020-05-19 18:32:38 +00:00
```shell-session
Update API docs
2017-04-04 16:33:22 +00:00
$ curl \
website: use 127.0.0.1 instead of consul.rocks (#4523) By default, the Consul agent listens on the local interface at port 8500 for API requests. This change makes the API examples using `curl` copy-pasteable for this default configuration.
2018-08-28 16:07:15 +00:00
http://127.0.0.1:8500/v1/session/node/node-abcd1234
Update API docs
2017-04-04 16:33:22 +00:00
```
### Sample Response
```json
[
{
website: update the response json fields for sessions (#4604) Updated the response json with the true response from Consul 1.2.2
2018-10-24 14:33:25 +00:00
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
"Name": "test-session",
docs: Update responses for /v1/session/ endpoints post 1.7 Update output for /v1/session/ endpoints to match output post Consul 1.7.0. Documents new `NodeChecks` and `ServiceChecks` parameters which were added in that release. Resolves #7341, resolves #10095
2021-07-20 06:52:21 +00:00
"Node": "node-abcd1234",
"LockDelay": 15000000000,
website: update the response json fields for sessions (#4604) Updated the response json with the true response from Consul 1.2.2
2018-10-24 14:33:25 +00:00
"Behavior": "release",
"TTL": "30s",
docs: Update responses for /v1/session/ endpoints post 1.7 Update output for /v1/session/ endpoints to match output post Consul 1.7.0. Documents new `NodeChecks` and `ServiceChecks` parameters which were added in that release. Resolves #7341, resolves #10095
2021-07-20 06:52:21 +00:00
"NodeChecks": [
"serfHealth"
],
"ServiceChecks": null,
website: update the response json fields for sessions (#4604) Updated the response json with the true response from Consul 1.2.2
2018-10-24 14:33:25 +00:00
"CreateIndex": 1086449,
"ModifyIndex": 1086449
}
Update API docs
2017-04-04 16:33:22 +00:00
]
```
## List Sessions
This endpoint returns the list of active sessions.
initial
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| :----- | :-------------- | ------------------ |
| `GET` | `/session/list` | `application/json` |
Update API docs
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
replace internal .html link extensions
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
remove internal /index.html
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
Update API docs
2017-04-04 16:33:22 +00:00
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | -------------- |
| `YES` | `all` | `none` | `session:read` |
Update API docs
2017-04-04 16:33:22 +00:00
### Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter. Using this across datacenters is not recommended.
initial
2020-04-06 20:27:35 +00:00
Add callouts to Enterprise features (#7548) Label all enterprise-related content with Enterprise badge/callout. Resolves #6887 Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com>
2020-04-23 22:13:18 +00:00
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
Revert "Remove docs refs to NS inference from ACL token" (#6976) This reverts commit 3a8426de9c76e7d8dd2728e4ae78bc4e5e18626a. # Conflicts: # command/flags/http.go # website/source/api/acl/binding-rules.html.md # website/source/api/acl/policies.html.md # website/source/api/acl/roles.html.md # website/source/api/acl/tokens.html.md # website/source/api/kv.html.md # website/source/api/session.html.md # website/source/docs/commands/_http_api_namespace_options.html.md
2019-12-20 16:52:50 +00:00
If not provided, the namespace will be inferred from the request's ACL token,
initial
2020-04-06 20:27:35 +00:00
or will default to the `default` namespace. This is specified as part of the URL as a query parameter.
The namespace may be specified as '\*' and then results will be returned for all namespaces.
Fix typos and add expand wildcard ns docs
2019-12-10 21:04:24 +00:00
Added in Consul 1.7.0.
Update API docs
2017-04-04 16:33:22 +00:00
### Sample Request
update dependencies
2020-05-19 18:32:38 +00:00
```shell-session
Update API docs
2017-04-04 16:33:22 +00:00
$ curl \
website: use 127.0.0.1 instead of consul.rocks (#4523) By default, the Consul agent listens on the local interface at port 8500 for API requests. This change makes the API examples using `curl` copy-pasteable for this default configuration.
2018-08-28 16:07:15 +00:00
http://127.0.0.1:8500/v1/session/list
Update API docs
2017-04-04 16:33:22 +00:00
```
### Sample Response
```json
[
{
website: update the response json fields for sessions (#4604) Updated the response json with the true response from Consul 1.2.2
2018-10-24 14:33:25 +00:00
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
"Name": "test-session",
initial
2020-04-06 20:27:35 +00:00
"Node": "raja-laptop-02",
docs: Update responses for /v1/session/ endpoints post 1.7 Update output for /v1/session/ endpoints to match output post Consul 1.7.0. Documents new `NodeChecks` and `ServiceChecks` parameters which were added in that release. Resolves #7341, resolves #10095
2021-07-20 06:52:21 +00:00
"LockDelay": 15000000000,
website: update the response json fields for sessions (#4604) Updated the response json with the true response from Consul 1.2.2
2018-10-24 14:33:25 +00:00
"Behavior": "release",
"TTL": "30s",
docs: Update responses for /v1/session/ endpoints post 1.7 Update output for /v1/session/ endpoints to match output post Consul 1.7.0. Documents new `NodeChecks` and `ServiceChecks` parameters which were added in that release. Resolves #7341, resolves #10095
2021-07-20 06:52:21 +00:00
"NodeChecks": [
"serfHealth"
],
"ServiceChecks": null,
website: update the response json fields for sessions (#4604) Updated the response json with the true response from Consul 1.2.2
2018-10-24 14:33:25 +00:00
"CreateIndex": 1086449,
"ModifyIndex": 1086449
}
Update API docs
2017-04-04 16:33:22 +00:00
]
```
## Renew Session
This endpoint renews the given session. This is used with sessions that have a
TTL, and it extends the expiration by the TTL.
initial
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| :----- | :--------------------- | ------------------ |
| `PUT` | `/session/renew/:uuid` | `application/json` |
Update API docs
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
replace internal .html link extensions
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
remove internal /index.html
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
Update API docs
2017-04-04 16:33:22 +00:00
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | --------------- |
| `NO` | `none` | `none` | `session:write` |
Update API docs
2017-04-04 16:33:22 +00:00
### Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the session to renew.
This is required and is specified as part of the URL path.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter. Using this across datacenters is not recommended.
initial
2020-04-06 20:27:35 +00:00
Add callouts to Enterprise features (#7548) Label all enterprise-related content with Enterprise badge/callout. Resolves #6887 Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com>
2020-04-23 22:13:18 +00:00
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to query.
Revert "Remove docs refs to NS inference from ACL token" (#6976) This reverts commit 3a8426de9c76e7d8dd2728e4ae78bc4e5e18626a. # Conflicts: # command/flags/http.go # website/source/api/acl/binding-rules.html.md # website/source/api/acl/policies.html.md # website/source/api/acl/roles.html.md # website/source/api/acl/tokens.html.md # website/source/api/kv.html.md # website/source/api/session.html.md # website/source/docs/commands/_http_api_namespace_options.html.md
2019-12-20 16:52:50 +00:00
If not provided, the namespace will be inferred from the request's ACL token,
or will default to the `default` namespace. This is specified as part of the
URL as a query parameter. Added in Consul 1.7.0.
Update API docs
2017-04-04 16:33:22 +00:00
### Sample Request
update dependencies
2020-05-19 18:32:38 +00:00
```shell-session
Update API docs
2017-04-04 16:33:22 +00:00
$ curl \
--request PUT \
website: use 127.0.0.1 instead of consul.rocks (#4523) By default, the Consul agent listens on the local interface at port 8500 for API requests. This change makes the API examples using `curl` copy-pasteable for this default configuration.
2018-08-28 16:07:15 +00:00
http://127.0.0.1:8500/v1/session/renew/adf4238a-882b-9ddc-4a9d-5b6758e4159e
Update API docs
2017-04-04 16:33:22 +00:00
```
### Sample Response
```json
[
{
website: update the response json fields for sessions (#4604) Updated the response json with the true response from Consul 1.2.2
2018-10-24 14:33:25 +00:00
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
"Name": "test-session",
initial
2020-04-06 20:27:35 +00:00
"Node": "raja-laptop-02",
docs: Update responses for /v1/session/ endpoints post 1.7 Update output for /v1/session/ endpoints to match output post Consul 1.7.0. Documents new `NodeChecks` and `ServiceChecks` parameters which were added in that release. Resolves #7341, resolves #10095
2021-07-20 06:52:21 +00:00
"LockDelay": 15000000000,
Update API docs
2017-04-04 16:33:22 +00:00
"Behavior": "release",
docs: Update responses for /v1/session/ endpoints post 1.7 Update output for /v1/session/ endpoints to match output post Consul 1.7.0. Documents new `NodeChecks` and `ServiceChecks` parameters which were added in that release. Resolves #7341, resolves #10095
2021-07-20 06:52:21 +00:00
"TTL": "30s",
"NodeChecks": [
"serfHealth"
],
"ServiceChecks": null,
website: update the response json fields for sessions (#4604) Updated the response json with the true response from Consul 1.2.2
2018-10-24 14:33:25 +00:00
"CreateIndex": 1086449,
"ModifyIndex": 1086449
Update API docs
2017-04-04 16:33:22 +00:00
}
]
```
-> **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.