Merge branch 'master' into aacrawfi_docs

concepts/publish-subscribe-messaging/pubsub_api.md

@@ -33,9 +33,11 @@ curl -X POST http://localhost:3500/v1.0/publish/deathStarStatus \
      }'
 ```
 
-## Handling topic subscriptions
+# Required Application (User Code) Routes
 
-In order to receive topic subscriptions, Dapr will invoke the following endpoint on user code:
+## Provide a route for Dapr to discover topic subscriptions
+
+Dapr will invoke the following endpoint on user code to discover topic subscriptions:
 
 ### HTTP Request
 
@@ -59,9 +61,9 @@ Example:
 "["TopicA","TopicB"]"
 ```
 
-## Delivering events to subscribers
+## Provide route(s) for Dapr to deliver topic events
 
-In order to deliver events to a subscribed application, a `POST` call should be made to user code with the name of the topic as the URL path.
+In order to deliver topic events, a `POST` call will be made to user code with the name of the topic as the URL path.
 
 The following example illustrates this point, considering a subscription for topic `TopicA`:
 

howto/README.md

@@ -21,7 +21,7 @@ Here you'll find a list of How To guides that walk you through accomplishing spe
 * [Use Pub/Sub to publish messages to a given topic](./publish-topic)
 * [Use Pub/Sub to consume events from a topic](./consume-topic)
 
-## Resources Bindings
+## Bindings and Triggers
 
 * [Trigger a service from different resources with input bindings](./trigger-app-with-input-binding)
 * [Invoke different resources using output bindings](./send-events-with-output-bindings)
@@ -40,7 +40,8 @@ Here you'll find a list of How To guides that walk you through accomplishing spe
 
 ## Secrets
 
-* [Configure secrets using Dapr secret stores](./setup-secret-store)
+* [Configure component secrets using Dapr secret stores](./setup-secret-store)
+* [Using the Secrets API to get application secrets](./get-secrets)
 
 ## Autoscaling
 

howto/get-secrets/README.md

@@ -0,0 +1,103 @@
+# Access Application Secrets using the Secrets API
+
+It's common for applications to store sensitive information such as connection strings, keys and tokens that are used to authenticate with databases, services and external systems in secrets by using a dedicated secret store.
+
+Usually this involves setting up a secret store such as Azure Key Vault, Hashicorp Vault and others and storing the application level secrets there. To access these secret stores, the application needs to import the secret store SDK, and use it to access the secrets.
+
+This usually involves writing a fair amount of boilerplate code that is not related to the actual business domain of the app, and this becomes an even greater challenge in multi-cloud scenarios: if an app needs to deploy to two different environments and use two different secret stores, the amount of boilerplate code gets doubled, and the effort increases.
+
+In addition, not all secret stores have native SDKs for all programming languages.
+
+To make it easier for developers everywhere to consume application secrets, Dapr has a dedicated secrets building block API that allows developers to get secrets from a secret store.
+
+## Setting up a secret store component
+
+The first step involves setting up a secret store, either in the cloud or in the hosting environment such as a cluster. This is done by using the relevant instructions from the cloud provider or secret store implementation.
+
+The second step is to configure the secret store with Dapr.
+
+Follow the instructions [here](../setup-secret-store) to set up the secret store of your choice.
+
+## Calling the secrets API
+
+Now that the secret store is set up, you can call Dapr to get the secrets for a given key for a specific secret store.
+
+For a full API reference, go [here](../../reference/api/secrets.md).
+
+Here are a few examples in different programming languages:
+
+### Go
+
+```Go
+import (
+  "fmt"
+  "net/http"
+)
+
+func main() {
+  url := "http://localhost:3500/v1.0/secrets/kubernetes/my-secret"
+
+  res, err := http.Get(url)
+  if err != nil {
+    panic(err)  
+  }
+  defer res.Body.Close()
+
+  body, _ := ioutil.ReadAll(res.Body)
+  fmt.Println(string(body))
+}
+```
+### Javascript
+
+```javascript
+require('isomorphic-fetch');
+const secretsUrl = `http://localhost:3500/v1.0/secrets`;
+
+fetch(`${secretsUrl}/kubernetes/my-secret`)
+        .then((response) => {
+            if (!response.ok) {
+                throw "Could not get secret";
+            }
+            return response.text();
+        }).then((secret) => {
+            console.log(secret);
+        });
+```
+
+### Python
+
+```python
+import requests as req
+
+resp = req.get("http://localhost:3500/v1.0/secrets/kubernetes/my-secret")
+print(resp.text)
+```
+
+### Rust
+
+```rust
+#![deny(warnings)]
+use std::{thread};
+
+#[tokio::main]
+async fn main() -> Result<(), reqwest::Error> {
+    let res = reqwest::get("http://localhost:3500/v1.0/secrets/kubernetes/my-secret").await?;
+    let body = res.text().await?;
+    println!("Secret:{}", body);
+
+    thread::park();
+
+    Ok(())
+}
+```
+
+### C#
+
+```csharp
+var client = new HttpClient();
+var response = await client.GetAsync("http://localhost:3500/v1.0/secrets/kubernetes/my-secret");
+response.EnsureSuccessStatusCode();
+
+string secret = await response.Content.ReadAsStringAsync();
+Console.WriteLine(secret);
+```