Updating the state API spec documentation for new multi state stores APIs (#295)

* Updating the state API spec documentation to add the details of multi state stores scenario.

* Resolving code review comments.

* Updating the api spec for multiple state store.

Co-authored-by: Young Bu Park <youngp@microsoft.com>
Co-authored-by: Aman Bhardwaj <amanbha@users.noreply.github.com>
This commit is contained in:
Shalabh Mohan Shrivastava 2020-02-06 14:23:34 -08:00 committed by GitHub
parent cd7049f9cb
commit f6c4a919f8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 36 additions and 7 deletions

View File

@ -25,6 +25,11 @@ 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.
Starting with 0.4.0 release, support for multiple state stores was added. This is a breaking change from previous releases as the state APIs were changed to support this new scenario.
Please refer https://github.com/dapr/dapr/blob/master/docs/decision_records/api/API-008-multi-state-store-api-design.md for more details.
## Key scheme
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:
```bash
@ -42,13 +47,14 @@ This endpoint lets you save an array of state objects.
### HTTP Request
`POST http://localhost:<daprPort>/v1.0/state`
`POST http://localhost:<daprPort>/v1.0/state/<storename>`
#### URL Parameters
Parameter | Description
--------- | -----------
daprPort | the Dapr port
storename | ```metadata.name``` field in the user configured state store component yaml. Please refer Dapr State Store configuration structure mentioned above.
#### Request Body
A JSON array of state objects. Each state object is comprised with the following fields:
@ -77,7 +83,7 @@ None.
### Example
```shell
curl -X POST http://localhost:3500/v1.0/state \
curl -X POST http://localhost:3500/v1.0/state/starwars \
-H "Content-Type: application/json" \
-d '[
{
@ -99,13 +105,14 @@ This endpoint lets you get the state for a specific key.
### HTTP Request
`GET http://localhost:<daprPor>/v1.0/state/<key>`
`GET http://localhost:<daprPor>/v1.0/state/<storename>/<key>`
#### URL Parameters
Parameter | Description
--------- | -----------
daprPort | the Dapr port
storename | ```metadata.name``` field in the user configured state store component yaml. Please refer Dapr State Store configuration structure mentioned above.
key | the key of the desired state
consistency | (optional) read consistency mode, see [state operation options](#optional-behaviors)
@ -132,7 +139,7 @@ JSON-encoded value
### Example
```shell
curl http://localhost:3500/v1.0/state/planet \
curl http://localhost:3500/v1.0/state/starwars/planet \
-H "Content-Type: application/json"
```
@ -149,13 +156,14 @@ This endpoint lets you delete the state for a specific key.
### HTTP Request
`DELETE http://localhost:<daprPort>/v1.0/state/<key>`
`DELETE http://localhost:<daprPort>/v1.0/state/<storename>/<key>`
#### URL Parameters
Parameter | Description
--------- | -----------
daprPort | the Dapr port
storename | ```metadata.name``` field in the user configured state store component yaml. Please refer Dapr State Store configuration structure mentioned above.
key | the key of the desired state
concurrency | (optional) either *first-write* or *last-write*, see [state operation options](#optional-behaviors)
consistency | (optional) either *strong* or *eventual*, see [state operation options](#optional-behaviors)
@ -185,7 +193,28 @@ None.
### Example
```shell
curl -X "DELETE" http://localhost:3500/v1.0/state/planet -H "ETag: xxxxxxx"
curl -X "DELETE" http://localhost:3500/v1.0/state/starwars/planet -H "ETag: xxxxxxx"
```
## Configuring State Store for Actors
Actors don't support multiple state stores and require a transactional state store to be used with Dapr. Currently mongodb and redis implement the transactional state store interface.
To specify which state store to be used for actors, specify value of property `actorStateStore` as true in the metadata section of the state store component yaml file.
Example: Following components yaml will configure redis to be used as the state store for Actors.
```
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: statestore
spec:
type: state.redis
metadata:
- name: redisHost
value: <redis host>
- name: redisPassword
value: ""
- name: actorStateStore
value: "true"
```
## Optional behaviors
@ -233,7 +262,7 @@ retryThreshold | Maximum number of retries.
The following is a sample *set* request with a complete operation option definition:
```shell
curl -X POST http://localhost:3500/v1.0/state \
curl -X POST http://localhost:3500/v1.0/state/starwars \
-H "Content-Type: application/json" \
-d '[
{