Dapr offers a reliable state endpoint that allows developers to save and retrieve state via an API. Dapr has a pluggable architecture and allows binding to a multitude of cloud/on-premises state stores.
Examples for state stores include Redis, Azure CosmosDB, AWS DynamoDB, GCP Cloud Spanner, Cassandra to name a few.
An Dapr State Store has the following structure:
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: <NAME>
spec:
type: state.<TYPE>
metadata:
- name:<KEY>
value:<VALUE>
- name: <KEY>
value: <VALUE>
The metadata.name is the name of the state store.
the spec/metadata section is an open key value pair metadata that allows a binding to define connection properties.
Dapr state stores are key/value stores. To ensure data compatibility, Dapr requires these data stores follow a fixed key scheme. For general states, the key format is:
<Dapr id>-<state key>For Actor states, the key format is:
<Dapr id>-<Actor type>-<Actor id>-<state key>This endpoint lets you save an array of state objects.
POST http://localhost:3500/v1.0/state
A JSON array of state objects. Each state object is comprised with the following fields:
| Field | Description |
|---|---|
| key | state key |
| value | state value, which can be any byte array |
| etag | (optional) state ETag |
| metadata | (optional) additional key-value pairs to be passed to the state store |
| options | (optional) state operation options, see state operation options |
ETag format Dapr runtime treats ETags as opaque strings. The exact ETag format is defined by the corresponding data store.
| Code | Description |
|---|---|
| 201 | State saved |
| 400 | State store is missing or misconfigured |
| 500 | Failed to save state |
None.
curl -X POST http://localhost:3500/v1.0/state \
-H "Content-Type: application/json"
-d '[
{
"key": "weapon",
"value": "DeathStar"
},
{
"key": "planet",
"value": {
"name": "Tatooine"
}
}
]'This endpoint lets you get the state for a specific key.
GET http://localhost:3500/v1.0/state/<key>
| Parameter | Description |
|---|---|
| key | the key of the desired state |
| consistency | (optional) read consistency mode, see state operation options |
| Code | Description |
|---|---|
| 200 | Get state successful |
| 204 | Key is not found |
| 400 | State store is missing or misconfigured |
| 500 | Get state failed |
| Header | Description |
|---|---|
| ETag | ETag of returned value |
JSON-encoded value
curl http://localhost:3500/v1.0/state/planet \
-H "Content-Type: application/json"The above command returns the state:
{
"name": "Tatooine"
}This endpoint lets you delete the state for a specific key.
DELETE http://localhost:3500/v1.0/state/<key>
| Parameter | Description |
|---|---|
| key | the key of the desired state |
| concurrency | (optional) either first-write or last-write, see state operation options |
| consistency | (optional) either strong or eventual, see state operation options |
| retryInterval | (optional) retry interval, in milliseconds, see retry policy |
| retryPattern | (optional) retyr pattern, can be either linear or exponential, see retry policy |
| retryThreshold | (optinal) number of retries, see retry policy |
| Header | Description |
|---|---|
| If-Match | (Optional) ETag associated with the key to be deleted |
| Code | Description |
|---|---|
| 200 | Delete state successful |
| 400 | State store is missing or misconfigured |
| 500 | Delete state failed |
None.
curl -X "DELETE" http://localhost:3500/v1.0/state/planet -H "ETag: xxxxxxx"A Dapr-compatible state store shall use the following key scheme:
- <Dapr id>-<state key> key format for general states
- <Dapr id>-<Actor type>-<Actor id>-<state key> key format for Actor states.
Dapr uses Optimized Concurrency Control (OCC) with ETags. Dapr imposes the following requirements on state stores:
- An Dapr-compatible state store shall support optimistic concurrency control using ETags. When an ETag is associated with an save or delete request, the store shall allow the update only if the attached ETag matches with the latest ETag in the database.
- When ETag is mssing in the write requests, the state store shall handle the reuqests in a last-write-wins fashion. This is to allow optimizations for high-throughput write scenarios in which data contingency is low or has no negative effects.
- A store shall always return ETags when returning states to callers.
Dapr allows clients to attach a consistency hint to get, set and delete operation. Dapr support two consistency level: strong and eventual, which are defined as the follows:
Dapr assumes data stores are eventually consistent by default. A state should:
- For read requests, the state store can return data from any of the replicas
- For write request, the state store should asynchronously replicate updates to configured quorum after acknowledging the update request.
When a strong consistency hint is attached, a state store should:
- For read requests, the state store should return the most up-to-date data consistently acorss replicas.
- For write/delete requests, the state store should synchronisely replicate updated data to configured quorum before completing the write request.
Dapr allows clients to attach retry policies to set and delete operations. A retry policy is described by three fields:
| Field | Description |
|---|---|
| retryInterval | Initial delay between retries, in milliseconds. The interval remains constant for linear retry pattern. The interval is doubled after each retry for exponential retry pattern. So, for exponential pattern, the delay after attempt n will be interval*2^(n-1). |
| retryPattern | Retry pattern, can be either linear or exponential. |
| retryThreshold | Maximum number of retries. |
The following is a sample set request with a complete operation option definition:
curl -X POST http://localhost:3500/v1.0/state \
-H "Content-Type: application/json"
-d '[
{
"key": "weapon",
"value": "DeathStar",
"etag": "xxxxx",
"options": {
"concurrency": "first-write",
"consistency": "strong",
"retryPolicy": {
"interval": 100,
"threshold" : 3,
"pattern": "exponential"
}
}
}
]'