mirror of
https://github.com/status-im/consul.git
synced 2025-01-11 14:24:39 +00:00
Adds documentation for the transaction endpoint.
This commit is contained in:
James Phillips
parent
04d99cd702
commit
17cd0ac4ec
@ -16,14 +16,14 @@ Each endpoint manages a different aspect of Consul:
|
||||
|
||||
* [acl](http/acl.html) - Access Control Lists
|
||||
* [agent](http/agent.html) - Consul Agent
|
||||
* [catalog](http/catalog.html) - Nodes and services
|
||||
* [coordinate](http/coordinate.html) - Network coordinates
|
||||
* [catalog](http/catalog.html) - Nodes and Services
|
||||
* [coordinate](http/coordinate.html) - Network Coordinates
|
||||
* [event](http/event.html) - User Events
|
||||
* [health](http/health.html) - Health checks
|
||||
* [kv](http/kv.html) - Key/Value store
|
||||
* [health](http/health.html) - Health Checks
|
||||
* [kv](http/kv.html) - Key/Value Store
|
||||
* [query](http/query.html) - Prepared Queries
|
||||
* [session](http/session.html) - Sessions
|
||||
* [status](http/status.html) - Consul system status
|
||||
* [status](http/status.html) - Consul System Status
|
||||
|
||||
Each of these is documented in detail at the links above. Consul also has a number
|
||||
of internal APIs which are purposely undocumented and subject to change.
|
||||
|
||||
@ -1,22 +1,29 @@
|
||||
---
|
||||
layout: "docs"
|
||||
page_title: "Key/Value store (HTTP)"
|
||||
page_title: "Key/Value Store (HTTP)"
|
||||
sidebar_current: "docs-agent-http-kv"
|
||||
description: >
|
||||
The KV endpoint is used to access Consul's simple key/value store, useful for storing
|
||||
The KV endpoints are used to access Consul's simple key/value store, useful for storing
|
||||
service configuration or other metadata.
|
||||
---
|
||||
|
||||
# Key/Value HTTP Endpoint
|
||||
# Key/Value Store Endpoints
|
||||
|
||||
The KV endpoint is used to access Consul's simple key/value store, useful for storing
|
||||
The KV endpoints are used to access Consul's simple key/value store, useful for storing
|
||||
service configuration or other metadata.
|
||||
|
||||
It has only a single endpoint:
|
||||
The following endpoints are supported:
|
||||
|
||||
/v1/kv/<key>
|
||||
* [`/v1/kv/<key>`](#single): Manages updates of individual keys, deletes of individual
|
||||
keys or key prefixes, and fetches of individual keys or key prefixes
|
||||
* [`/v1/txn`](#txn): Manages updates or fetches of multiple keys inside a single,
|
||||
atomic transaction
|
||||
|
||||
The `GET`, `PUT` and `DELETE` methods are all supported.
|
||||
### <a name="single"></a> /v1/kv/<key>
|
||||
|
||||
This endpoint manages updates of individual keys, deletes of individual keys or key
|
||||
prefixes, and fetches of individual keys or key prefixes. The `GET`, `PUT` and
|
||||
`DELETE` methods are all supported.
|
||||
|
||||
By default, the datacenter of the agent is queried; however, the dc can be provided
|
||||
using the "?dc=" query parameter. It is important to note that each datacenter has
|
||||
@ -24,9 +31,9 @@ its own KV store, and there is no built-in replication between datacenters. If y
|
||||
are interested in replication between datacenters, look at the
|
||||
[Consul Replicate project](https://github.com/hashicorp/consul-replicate).
|
||||
|
||||
The KV endpoint supports the use of ACL tokens.
|
||||
The KV endpoint supports the use of ACL tokens using the "?token=" query parameter.
|
||||
|
||||
### GET Method
|
||||
#### GET Method
|
||||
|
||||
When using the `GET` method, Consul will return the specified key.
|
||||
If the "?recurse" query parameter is provided, it will return
|
||||
@ -67,7 +74,7 @@ the lock.
|
||||
|
||||
`Key` is simply the full path of the entry.
|
||||
|
||||
`Flags` are an opaque unsigned integer that can be attached to each entry. Clients
|
||||
`Flags` is an opaque unsigned integer that can be attached to each entry. Clients
|
||||
can choose to use this however makes sense for their application.
|
||||
|
||||
`Value` is a Base64-encoded blob of data. Note that values cannot be larger than
|
||||
@ -96,7 +103,7 @@ encoding.
|
||||
|
||||
If no entries are found, a 404 code is returned.
|
||||
|
||||
### PUT method
|
||||
#### PUT method
|
||||
|
||||
When using the `PUT` method, Consul expects the request body to be the
|
||||
value corresponding to the key. There are a number of query parameters that can
|
||||
@ -128,7 +135,7 @@ be used with a PUT request:
|
||||
The return value is either `true` or `false`. If `false` is returned,
|
||||
the update has not taken place.
|
||||
|
||||
### DELETE method
|
||||
#### DELETE method
|
||||
|
||||
The `DELETE` method can be used to delete a single key or all keys sharing
|
||||
a prefix. There are a few query parameters that can be used with a
|
||||
@ -142,3 +149,207 @@ DELETE request:
|
||||
synchronization primitives. Unlike `PUT`, the index must be greater than 0
|
||||
for Consul to take any action: a 0 index will not delete the key. If the index
|
||||
is non-zero, the key is only deleted if the index matches the `ModifyIndex` of that key.
|
||||
|
||||
### <a name="txn"></a> /v1/txn
|
||||
|
||||
Available in Consul 0.7 and later, this endpoint manages updates or fetches of
|
||||
multiple keys inside a single, atomic transaction. Only the `PUT` method is supported.
|
||||
|
||||
By default, the datacenter of the agent receives the transaction; however, the dc
|
||||
can be provided using the "?dc=" query parameter. It is important to note that each
|
||||
datacenter has its own KV store, and there is no built-in replication between
|
||||
datacenters. If you are interested in replication between datacenters, look at the
|
||||
[Consul Replicate project](https://github.com/hashicorp/consul-replicate).
|
||||
|
||||
The transaction endpoint supports the use of ACL tokens using the "?token=" query
|
||||
parameter.
|
||||
|
||||
#### PUT Method
|
||||
|
||||
The `PUT` method lets you submit a list of operations to apply to the key/value store
|
||||
inside a transaction. If any operation fails, the transaction will be rolled back and
|
||||
none of the changes will be applied.
|
||||
|
||||
The body of the request should be a list of operations to perform inside the atomic
|
||||
transaction, which looks like this:
|
||||
|
||||
```javascript
|
||||
[
|
||||
{
|
||||
"KV": {
|
||||
"Verb": "<verb>",
|
||||
"Key": "<key>",
|
||||
"Value": "<Base64-encoded blob of data>",
|
||||
"Flags": <flags>,
|
||||
"Index": <index>,
|
||||
"Session": "<session id>"
|
||||
}
|
||||
},
|
||||
...
|
||||
]
|
||||
```
|
||||
|
||||
`KV` is the only available operation type, though other types of operations may be added
|
||||
in future versions of Consul to be mixed with key/value operations. The following fields
|
||||
are available:
|
||||
|
||||
* `Verb` is the type of operation to perform. Please see the table below for
|
||||
available verbs.
|
||||
|
||||
* `Key` is simply the full path of the entry.
|
||||
|
||||
* `Value` is a Base64-encoded blob of data. Note that values cannot be larger than
|
||||
512kB.
|
||||
|
||||
* `Flags` is an opaque unsigned integer that can be attached to each entry. Clients
|
||||
can choose to use this however makes sense for their application.
|
||||
|
||||
* `Index` and `Session` are used for locking, unlocking, and check-and-set operations.
|
||||
Please see the table below for details on how they are used.
|
||||
|
||||
The following table summarizes the available verbs and the fields that apply to that
|
||||
operation ("X" means a field is required and "O" means it is optional):
|
||||
|
||||
<table class="table table-bordered table-striped">
|
||||
<tr>
|
||||
<th>Verb</th>
|
||||
<th>Operation</th>
|
||||
<th>Key</th>
|
||||
<th>Value</th>
|
||||
<th>Flags</th>
|
||||
<th>Index</th>
|
||||
<th>Session</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>set</td>
|
||||
<td>Sets the `Key` to the given `Value`.</td>
|
||||
<td align="center">X</td>
|
||||
<td align="center">X</td>
|
||||
<td align="center">O</td>
|
||||
<td align="center"></td>
|
||||
<td align="center"></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>cas</td>
|
||||
<td>Sets the `Key` to the given `Value` with check-and-set semantics. The `Key` will only be set if its current modify index matches the supplied `Index`.</td>
|
||||
<td align="center">X</td>
|
||||
<td align="center">X</td>
|
||||
<td align="center">O</td>
|
||||
<td align="center">X</td>
|
||||
<td align="center"></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>lock</td>
|
||||
<td>Locks the `Key` with the given `Session`. The `Key` will only obtain the lock if the `Session` is valid, and no other session has it locked.</td>
|
||||
<td align="center">X</td>
|
||||
<td align="center">X</td>
|
||||
<td align="center">O</td>
|
||||
<td align="center"></td>
|
||||
<td align="center">X</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>unlock</td>
|
||||
<td>Unlocks the `Key` with the given `Session`. The `Key` will only release the lock if the `Session` is valid and currently has it locked..</td>
|
||||
<td align="center">X</td>
|
||||
<td align="center">X</td>
|
||||
<td align="center">O</td>
|
||||
<td align="center"></td>
|
||||
<td align="center">X</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>get</td>
|
||||
<td>Gets the `Key` during the transaction. This fails the transaction if the `Key` doesn't exist.</td>
|
||||
<td align="center">X</td>
|
||||
<td align="center"></td>
|
||||
<td align="center"></td>
|
||||
<td align="center"></td>
|
||||
<td align="center"></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>check-index</td>
|
||||
<td>Fails the transaction if `Key` does not have a modify index equal to `Index`.</td>
|
||||
<td align="center">X</td>
|
||||
<td align="center"></td>
|
||||
<td align="center"></td>
|
||||
<td align="center">X</td>
|
||||
<td align="center"></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>check-session</td>
|
||||
<td>Fails the transaction if `Key` is not currently locked by `Session`.</td>
|
||||
<td align="center">X</td>
|
||||
<td align="center"></td>
|
||||
<td align="center"></td>
|
||||
<td align="center"></td>
|
||||
<td align="center">X</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>delete</td>
|
||||
<td>Deletes the `Key`.</td>
|
||||
<td align="center">X</td>
|
||||
<td align="center"></td>
|
||||
<td align="center"></td>
|
||||
<td align="center"></td>
|
||||
<td align="center"></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>delete-tree</td>
|
||||
<td>Deletes all keys with a prefix of`Key`.</td>
|
||||
<td align="center">X</td>
|
||||
<td align="center"></td>
|
||||
<td align="center"></td>
|
||||
<td align="center"></td>
|
||||
<td align="center"></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>delete-cas</td>
|
||||
<td>Deletes the `Key` with check-and-set semantics. The `Key` will only be deleted if its current modify index matches the supplied `Index`.</td>
|
||||
<td align="center">X</td>
|
||||
<td align="center"></td>
|
||||
<td align="center"></td>
|
||||
<td align="center">X</td>
|
||||
<td align="center"></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
If the transaction can be processed, a status code of 200 will be returned if it
|
||||
was successfully applied, or a status code of 409 will be returned if it was rolled
|
||||
back. If either of these status codes are returned, the response will look like this:
|
||||
|
||||
```javascript
|
||||
{
|
||||
"Results": [
|
||||
{
|
||||
"KV": {
|
||||
"LockIndex": <lock index>,
|
||||
"Key": "<key>",
|
||||
"Flags": <flags>,
|
||||
"Value": "<Base64-encoded blob of data, or null>",
|
||||
"CreateIndex": <index>,
|
||||
"ModifyIndex": <index>
|
||||
}
|
||||
},
|
||||
...
|
||||
],
|
||||
"Errors": [
|
||||
{
|
||||
"OpIndex": <index of failed operation>,
|
||||
"What": "<error message for failed operation>"
|
||||
},
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`Results` has an entry for each operation if the transaction was successful. To save
|
||||
space, the `Value` will be `null` for any `Verb` other than "get". Like the `/v1/kv/<key>`
|
||||
endpoint, `Value` will be Base64-encoded if it is present. For verbs that delete
|
||||
keys, a `null` result entry will be present, keeping the list of `Results` 1:1 with the
|
||||
list of operations given in the transaction.
|
||||
|
||||
`Errors` has entries describing which operations failed if the transaction was rolled
|
||||
back. The `OpIndex` gives the index of the failed operation in the transaction, and
|
||||
`What` is a string with an error message about why that operation failed.
|
||||
|
||||
If any other status code is returned, such as 400 or 500, then the body of the response
|
||||
will simply be an unstructured error message about what happened.
|
||||
|
||||
@ -171,7 +171,7 @@
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-agent-http-kv") %>>
|
||||
<a href="/docs/agent/http/kv.html">Key/Value store</a>
|
||||
<a href="/docs/agent/http/kv.html">Key/Value Store</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-agent-http-coordinate") %>>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user