github.com/outbrain/consul@v1.4.5/website/source/api/session.html.md (about) 1 --- 2 layout: api 3 page_title: Session - HTTP API 4 sidebar_current: api-session 5 description: |- 6 The /session endpoints create, destroy, and query sessions in Consul. 7 --- 8 9 # Session HTTP Endpoint 10 11 The `/session` endpoints create, destroy, and query sessions in Consul. 12 13 ## Create Session 14 15 This endpoint initializes a new session. Sessions must be associated with a 16 node and may be associated with any number of checks. 17 18 | Method | Path | Produces | 19 | ------ | ---------------------------- | -------------------------- | 20 | `PUT` | `/session/create` | `application/json` | 21 22 The table below shows this endpoint's support for 23 [blocking queries](/api/index.html#blocking-queries), 24 [consistency modes](/api/index.html#consistency-modes), 25 [agent caching](/api/index.html#agent-caching), and 26 [required ACLs](/api/index.html#acls). 27 28 | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 29 | ---------------- | ----------------- | ------------- | --------------- | 30 | `NO` | `none` | `none` | `session:write` | 31 32 ### Parameters 33 34 - `dc` `(string: "")` - Specifies the datacenter to query. This will default to 35 the datacenter of the agent being queried. This is specified as part of the 36 URL as a query parameter. Using this across datacenters is not recommended. 37 38 - `LockDelay` `(string: "15s")` - Specifies the duration for the lock delay. 39 40 - `Node` `(string: "<agent>")` - Specifies the name of the node. This must refer 41 to a node that is already registered. 42 43 - `Name` `(string: "")` - Specifies a human-readable name for the session. 44 45 - `Checks` `(array<string>: nil)` - specifies a list of associated health 46 check IDs (commonly `CheckID` in API responses). It is highly recommended that, 47 if you override this list, you include the default `serfHealth`. 48 49 - `Behavior` `(string: "release")` - Controls the behavior to take when a 50 session is invalidated. Valid values are: 51 52 - `release` - causes any locks that are held to be released 53 - `delete` - causes any locks that are held to be deleted 54 55 - `TTL` `(string: "")` - Specifies the number of seconds (between 10s and 56 86400s). If provided, the session is invalidated if it is not renewed before 57 the TTL expires. The lowest practical TTL should be used to keep the number of 58 managed sessions low. When locks are forcibly expired, such as during a leader 59 election, sessions may not be reaped for up to double this TTL, so long TTL 60 values (> 1 hour) should be avoided. 61 62 ### Sample Payload 63 64 ```json 65 { 66 "LockDelay": "15s", 67 "Name": "my-service-lock", 68 "Node": "foobar", 69 "Checks": ["a", "b", "c"], 70 "Behavior": "release", 71 "TTL": "30s" 72 } 73 ``` 74 75 ### Sample Request 76 77 ```text 78 $ curl \ 79 --request PUT \ 80 --data @payload.json \ 81 http://127.0.0.1:8500/v1/session/create 82 ``` 83 84 ### Sample Response 85 86 ```javascript 87 { 88 "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e" 89 } 90 ``` 91 92 - `ID` - the ID of the created session 93 94 ## Delete Session 95 96 This endpoint destroys the session with the given name. If the session UUID is 97 malformed, an error is returned. If the session UUID does not exist or already 98 expired, a 200 is still returned (the operation is idempotent). 99 100 | Method | Path | Produces | 101 | :----- | :--------------------------- | -------------------------- | 102 | `PUT` | `/session/destroy/:uuid` | `application/json` | 103 104 Even though the Content-Type is `application/json`, the response is 105 either a literal `true` or `false`, indicating of whether the destroy was 106 successful. 107 108 The table below shows this endpoint's support for 109 [blocking queries](/api/index.html#blocking-queries), 110 [consistency modes](/api/index.html#consistency-modes), 111 [agent caching](/api/index.html#agent-caching), and 112 [required ACLs](/api/index.html#acls). 113 114 | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 115 | ---------------- | ----------------- | ------------- | --------------- | 116 | `NO` | `none` | `none` | `session:write` | 117 118 ### Parameters 119 120 - `uuid` `(string: <required>)` - Specifies the UUID of the session to destroy. 121 This is required and is specified as part of the URL path. 122 123 - `dc` `(string: "")` - Specifies the datacenter to query. This will default to 124 the datacenter of the agent being queried. This is specified as part of the 125 URL as a query parameter. Using this across datacenters is not recommended. 126 127 ### Sample Request 128 129 ```text 130 $ curl \ 131 --request PUT 132 http://127.0.0.1:8500/v1/session/destroy/adf4238a-882b-9ddc-4a9d-5b6758e4159e 133 ``` 134 135 ### Sample Response 136 137 ```json 138 true 139 ``` 140 141 ## Read Session 142 143 This endpoint returns the requested session information. 144 145 | Method | Path | Produces | 146 | :----- | :--------------------------- | -------------------------- | 147 | `GET` | `/session/info/:uuid` | `application/json` | 148 149 The table below shows this endpoint's support for 150 [blocking queries](/api/index.html#blocking-queries), 151 [consistency modes](/api/index.html#consistency-modes), 152 [agent caching](/api/index.html#agent-caching), and 153 [required ACLs](/api/index.html#acls). 154 155 | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 156 | ---------------- | ----------------- | ------------- | -------------- | 157 | `YES` | `all` | `none` | `session:read` | 158 159 ### Parameters 160 161 - `uuid` `(string: <required>)` - Specifies the UUID of the session to read. 162 This is required and is specified as part of the URL path. 163 164 - `dc` `(string: "")` - Specifies the datacenter to query. This will default to 165 the datacenter of the agent being queried. This is specified as part of the 166 URL as a query parameter. Using this across datacenters is not recommended. 167 168 ### Sample Request 169 170 ```text 171 $ curl \ 172 http://127.0.0.1:8500/v1/session/info/adf4238a-882b-9ddc-4a9d-5b6758e4159e 173 ``` 174 175 ### Sample Response 176 177 ```json 178 [ 179 { 180 "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e", 181 "Name": "test-session", 182 "Node": "raja-laptop-02", 183 "Checks": [ 184 "serfHealth" 185 ], 186 "LockDelay": 1.5e+10, 187 "Behavior": "release", 188 "TTL": "30s", 189 "CreateIndex": 1086449, 190 "ModifyIndex": 1086449 191 } 192 ] 193 ``` 194 195 If the session does not exist, `null` is returned instead of a JSON list. 196 197 ## List Sessions for Node 198 199 This endpoint returns the active sessions for a given node. 200 201 | Method | Path | Produces | 202 | :----- | :--------------------------- | -------------------------- | 203 | `GET` | `/session/node/:node` | `application/json` | 204 205 The table below shows this endpoint's support for 206 [blocking queries](/api/index.html#blocking-queries), 207 [consistency modes](/api/index.html#consistency-modes), 208 [agent caching](/api/index.html#agent-caching), and 209 [required ACLs](/api/index.html#acls). 210 211 | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 212 | ---------------- | ----------------- | ------------- | -------------- | 213 | `YES` | `all` | `none` | `session:read` | 214 215 ### Parameters 216 217 - `node` `(string: <required>)` - Specifies the name or ID of the node to query. 218 This is required and is specified as part of the URL path. 219 220 - `dc` `(string: "")` - Specifies the datacenter to query. This will default to 221 the datacenter of the agent being queried. This is specified as part of the 222 URL as a query parameter. Using this across datacenters is not recommended. 223 224 ### Sample Request 225 226 ```text 227 $ curl \ 228 http://127.0.0.1:8500/v1/session/node/node-abcd1234 229 ``` 230 231 ### Sample Response 232 233 ```json 234 [ 235 { 236 "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e", 237 "Name": "test-session", 238 "Node": "raja-laptop-02", 239 "Checks": [ 240 "serfHealth" 241 ], 242 "LockDelay": 1.5e+10, 243 "Behavior": "release", 244 "TTL": "30s", 245 "CreateIndex": 1086449, 246 "ModifyIndex": 1086449 247 } 248 ] 249 ``` 250 251 ## List Sessions 252 253 This endpoint returns the list of active sessions. 254 255 | Method | Path | Produces | 256 | :----- | :--------------------------- | -------------------------- | 257 | `GET` | `/session/list` | `application/json` | 258 259 The table below shows this endpoint's support for 260 [blocking queries](/api/index.html#blocking-queries), 261 [consistency modes](/api/index.html#consistency-modes), 262 [agent caching](/api/index.html#agent-caching), and 263 [required ACLs](/api/index.html#acls). 264 265 | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 266 | ---------------- | ----------------- | ------------- | -------------- | 267 | `YES` | `all` | `none` | `session:read` | 268 269 ### Parameters 270 271 - `dc` `(string: "")` - Specifies the datacenter to query. This will default to 272 the datacenter of the agent being queried. This is specified as part of the 273 URL as a query parameter. Using this across datacenters is not recommended. 274 275 ### Sample Request 276 277 ```text 278 $ curl \ 279 http://127.0.0.1:8500/v1/session/list 280 ``` 281 282 ### Sample Response 283 284 ```json 285 [ 286 { 287 "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e", 288 "Name": "test-session", 289 "Node": "raja-laptop-02", 290 "Checks": [ 291 "serfHealth" 292 ], 293 "LockDelay": 1.5e+10, 294 "Behavior": "release", 295 "TTL": "30s", 296 "CreateIndex": 1086449, 297 "ModifyIndex": 1086449 298 } 299 ] 300 ``` 301 302 ## Renew Session 303 304 This endpoint renews the given session. This is used with sessions that have a 305 TTL, and it extends the expiration by the TTL. 306 307 | Method | Path | Produces | 308 | :----- | :--------------------------- | -------------------------- | 309 | `PUT` | `/session/renew/:uuid` | `application/json` | 310 311 The table below shows this endpoint's support for 312 [blocking queries](/api/index.html#blocking-queries), 313 [consistency modes](/api/index.html#consistency-modes), 314 [agent caching](/api/index.html#agent-caching), and 315 [required ACLs](/api/index.html#acls). 316 317 | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 318 | ---------------- | ----------------- | ------------- | --------------- | 319 | `NO` | `none` | `none` | `session:write` | 320 321 ### Parameters 322 323 - `uuid` `(string: <required>)` - Specifies the UUID of the session to renew. 324 This is required and is specified as part of the URL path. 325 326 - `dc` `(string: "")` - Specifies the datacenter to query. This will default to 327 the datacenter of the agent being queried. This is specified as part of the 328 URL as a query parameter. Using this across datacenters is not recommended. 329 330 ### Sample Request 331 332 ```text 333 $ curl \ 334 --request PUT \ 335 http://127.0.0.1:8500/v1/session/renew/adf4238a-882b-9ddc-4a9d-5b6758e4159e 336 ``` 337 338 ### Sample Response 339 340 ```json 341 [ 342 { 343 "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e", 344 "Name": "test-session", 345 "Node": "raja-laptop-02", 346 "Checks": [ 347 "serfHealth" 348 ], 349 "LockDelay": 1.5e+10, 350 "Behavior": "release", 351 "TTL": "15s", 352 "CreateIndex": 1086449, 353 "ModifyIndex": 1086449 354 } 355 ] 356 ``` 357 358 -> **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.