From b5519485d9ab4052ab1da8a44c9017fe904a4fae Mon Sep 17 00:00:00 2001 From: Yaron Schneider Date: Fri, 24 Jun 2022 14:12:51 -0700 Subject: [PATCH] Add configuration api http reference (#2569) * add configuration api http reference Signed-off-by: yaron2 * Update daprdocs/content/en/reference/api/configuration_api.md Co-authored-by: Mark Fussell * fix return code Signed-off-by: yaron2 * remove component section Signed-off-by: yaron2 * Update daprdocs/content/en/reference/api/configuration_api.md Co-authored-by: Mark Fussell * get all items example Signed-off-by: yaron2 * change to v1.0-alpha1 Signed-off-by: yaron2 * param name Signed-off-by: yaron2 * added subscription section, fix typo Signed-off-by: yaron2 * subscribe all example Signed-off-by: yaron2 * add mystore Signed-off-by: yaron2 * routes Signed-off-by: yaron2 * id Signed-off-by: yaron2 * feedback Signed-off-by: yaron2 * feedback Signed-off-by: yaron2 Co-authored-by: Mark Fussell --- .../en/reference/api/configuration_api.md | 234 ++++++++++++++++++ 1 file changed, 234 insertions(+) create mode 100644 daprdocs/content/en/reference/api/configuration_api.md diff --git a/daprdocs/content/en/reference/api/configuration_api.md b/daprdocs/content/en/reference/api/configuration_api.md new file mode 100644 index 000000000..68e406f5b --- /dev/null +++ b/daprdocs/content/en/reference/api/configuration_api.md @@ -0,0 +1,234 @@ +--- +type: docs +title: "Configuration API reference" +linkTitle: "Configuration API" +description: "Detailed documentation on the configuration API" +weight: 650 +--- + +## Get Configuration + +This endpoint lets you get configuration from a store. + +### HTTP Request + +``` +GET http://localhost:/v1.0-alpha1/configuration/ +``` + +#### URL Parameters + +Parameter | Description +--------- | ----------- +`daprPort` | The Dapr port +`storename` | The `metadata.name` field component file. Refer to the [component schema] ({{< ref component-schema.md>}}) + +#### Query Parameters + +If no query parameters are provided, all configuration items are returned. +To specifiy the keys of the configuration items to get, use one or more `key` query parameters. For example: + +``` +GET http://localhost:/v1.0-alpha1/configuration/mystore?key=config1&key=config2 +``` + +To retrieve all configuration items: + +``` +GET http://localhost:/v1.0-alpha1/configuration/mystore +``` + +#### Request Body + +None + +### HTTP Response + +#### Response Codes + +Code | Description +---- | ----------- +`204` | Get operation successful +`400` | Configuration store is missing or misconfigured or malformed request +`500` | Failed to get configuration + +#### Response Body + +JSON-encoded value of key/value pairs for each configuration item. + +### Example + +```shell +curl -X GET 'http://localhost:3500/v1.0-alpha1/configuration/mystore?key=myConfigKey' +``` + +> The above command returns the following JSON: + +```json +[{"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 + +``` +GET http://localhost:/v1.0-alpha1/configuration//subscribe +``` + +#### URL Parameters + +Parameter | Description +--------- | ----------- +`daprPort` | The Dapr port +`storename` | The `metadata.name` field component file. Refer to the [component schema] ({{< ref component-schema.md>}}) + +#### Query Parameters + +If no query parameters are provided, all configuration items are subscribed to. +To specifiy the keys of the configuration items to subscribe to, use one or more `key` query parameters. For example: + +``` +GET http://localhost:/v1.0-alpha1/configuration/mystore/subscribe?key=config1&key=config2 +``` + +To subscribe to all changes: + +``` +GET http://localhost:/v1.0-alpha1/configuration/mystore/subscribe +``` + +#### Request Body + +None + +### HTTP Response + +#### Response Codes + +Code | Description +---- | ----------- +`200` | Subscribe operation successful +`400` | Configuration store is missing or misconfigured or malformed request +`500` | Failed to subscribe to configuration changes + +#### Response Body + +JSON-encoded value + +### Example + +```shell +curl -X GET 'http://localhost:3500/v1.0-alpha1/configuration/mystore/subscribe?key=myConfigKey' +``` + +> The above command returns the following JSON: + +```json +{ + "id": "" +} +``` + +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 + +``` +GET http://localhost:/v1.0-alpha1/configuration//unsubscribe +``` + +#### URL Parameters + +Parameter | Description +--------- | ----------- +`daprPort` | The Dapr port +`subscription-id` | The value from the `id` field returned from the response of the subscribe endpoint + +#### Query Parameters + +None + +#### Request Body + +None + +### HTTP Response + +#### Response Codes + +Code | Description +---- | ----------- +`204` | Unsubscribe operation successful +`400` | Configuration store is missing or misconfigured or malformed request +`500` | Failed to unsubscribe to configuration changes + +#### Response Body + +None + +### Example + +```shell +curl -X GET 'http://localhost:3500/v1.0-alpha1/configuration/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 `/` and for a specific key by adding `//` to the route. + +#### HTTP Request + +``` +POST http://localhost:/configuration// +``` + +#### URL Parameters + +Parameter | Description +--------- | ----------- +`appPort` | The application port +`storename` | The `metadata.name` field component file. Refer to the [component schema] ({{< ref component-schema.md>}}) +`key` | The 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. + +```json +{ + "id": "", + "items": [ + "key": "", + "value": "", + "version": "" + ] +} +``` + +#### Example + +```json +{ + "id": "bf3aa454-312d-403c-af95-6dec65058fa2", + "items": [ + "key": "config-1", + "value": "abcdefgh", + "version": "1.1" + ] +} +``` + + +## Next Steps + +- [Configuration API overview]({{< ref configuration-api-overview.md >}}) +- [How-To: Manage configuration from a store]({{< ref howto-manage-configuration.md >}}) \ No newline at end of file