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.