Configuration API reference

Detailed documentation on the configuration API

Get Configuration

This endpoint lets you get configuration from a store.

HTTP Request

  1. GET http://localhost:<daprPort>/v1.0-alpha1/configuration/<storename>

URL Parameters

ParameterDescription
daprPortThe Dapr port
storenameThe metadata.name field component file. Refer to the component schema

Query Parameters

If no query parameters are provided, all configuration items are returned. To specify the keys of the configuration items to get, use one or more key query parameters. For example:

  1. GET http://localhost:<daprPort>/v1.0-alpha1/configuration/mystore?key=config1&key=config2

To retrieve all configuration items:

  1. GET http://localhost:<daprPort>/v1.0-alpha1/configuration/mystore

Request Body

None

HTTP Response

Response Codes

CodeDescription
204Get operation successful
400Configuration store is missing or misconfigured or malformed request
500Failed to get configuration

Response Body

JSON-encoded value of key/value pairs for each configuration item.

Example

  1. curl -X GET 'http://localhost:3500/v1.0-alpha1/configuration/mystore?key=myConfigKey'

The above command returns the following JSON:

  1. [{"key":"myConfigKey","value":"myConfigValue"}]

Subscribe Configuration

This endpoint lets you subscribe to configuration changes. Notifications happen when values are updated or deleted in the configuration store. This enables the application to react to configuration changes.

HTTP Request

  1. GET http://localhost:<daprPort>/v1.0-alpha1/configuration/<storename>/subscribe

URL Parameters

ParameterDescription
daprPortThe Dapr port
storenameThe metadata.name field component file. Refer to the component schema

Query Parameters

If no query parameters are provided, all configuration items are subscribed to. To specify the keys of the configuration items to subscribe to, use one or more key query parameters. For example:

  1. GET http://localhost:<daprPort>/v1.0-alpha1/configuration/mystore/subscribe?key=config1&key=config2

To subscribe to all changes:

  1. GET http://localhost:<daprPort>/v1.0-alpha1/configuration/mystore/subscribe

Request Body

None

HTTP Response

Response Codes

CodeDescription
200Subscribe operation successful
400Configuration store is missing or misconfigured or malformed request
500Failed to subscribe to configuration changes

Response Body

JSON-encoded value

Example

  1. curl -X GET 'http://localhost:3500/v1.0-alpha1/configuration/mystore/subscribe?key=myConfigKey'

The above command returns the following JSON:

  1. {
  2. "id": "<unique-id>"
  3. }

The returned id parameter can be used to unsubscribe to the specific set of keys provided on the subscribe API call. This should be retained by the application.

Unsubscribe Configuration

This endpoint lets you unsubscribe to configuration changes.

HTTP Request

  1. GET http://localhost:<daprPort>/v1.0-alpha1/configuration/<storename>/<subscription-id>/unsubscribe

URL Parameters

ParameterDescription
daprPortThe Dapr port
storenameThe metadata.name field component file. Refer to the component schema
subscription-idThe value from the id field returned from the response of the subscribe endpoint

Query Parameters

None

Request Body

None

HTTP Response

Response Codes

CodeDescription
200Unsubscribe operation successful
400Configuration store is missing or misconfigured or malformed request
500Failed to unsubscribe to configuration changes

Response Body

  1. {
  2. "ok" : true
  3. }

Example

  1. curl -X GET 'http://localhost:3500/v1.0-alpha1/configuration/mystore/bf3aa454-312d-403c-af95-6dec65058fa2/unsubscribe'

Optional application (user code) routes

Provide a route for Dapr to send configuration changes

subscribing to configuration changes, Dapr invokes the application whenever a configuration item changes. Your application can have a /configuration endpoint that is called for all key updates that are subscribed to. The endpoint(s) can be made more specific for a given configuration store by adding /<store-name> and for a specific key by adding /<store-name>/<key> to the route.

HTTP Request

  1. POST http://localhost:<appPort>/configuration/<store-name>/<key>

URL Parameters

ParameterDescription
appPortThe application port
storenameThe metadata.name field component file. Refer to the component schema
keyThe key subscribed to

Request Body

A list of configuration items for a given subscription id. Configuration items can have a version associated with them, which is returned in the notification.

  1. {
  2. "id": "<subscription-id>",
  3. "items": [
  4. "key": "<key-of-configuration-item>",
  5. "value": "<new-value>",
  6. "version": "<version-of-item>"
  7. ]
  8. }

Example

  1. {
  2. "id": "bf3aa454-312d-403c-af95-6dec65058fa2",
  3. "items": [
  4. "key": "config-1",
  5. "value": "abcdefgh",
  6. "version": "1.1"
  7. ]
  8. }

Next Steps

Last modified September 27, 2022: Fix Configuration API unsubscribe endpoint (#2797) (1bbdb328)