Extend service invocation to non-Dapr endpoints docs

daprdocs/content/en/concepts/terminology.md

@@ -16,6 +16,7 @@ This page details all of the common terms you may come across in the Dapr docs.
 | Configuration | A YAML file declaring all of the settings for Dapr sidecars or the Dapr control plane. This is where you can configure control plane mTLS settings, or the tracing and middleware settings for an application instance. | [Dapr configuration]({{< ref configuration-concept.md >}})
 | Dapr | Distributed Application Runtime. | [Dapr overview]({{< ref overview.md >}})
 | Dapr control plane | A collection of services that are part of a Dapr installation on a hosting platform such as a Kubernetes cluster. This allows Dapr-enabled applications to run on the platform and handles Dapr capabilities such as actor placement, Dapr sidecar injection, or certificate issuance/rollover. | [Self-hosted overview]({{< ref self-hosted-overview >}})<br />[Kubernetes overview]({{< ref kubernetes-overview >}})
+| HTTPEndpoint | HTTPEndpoint is a Dapr resource use to identify non-Dapr endpoints to invoke via the service invocation API. | [Service invocation API]({{< ref service_invocation_api.md >}})
 | Self-hosted | Windows/macOS/Linux machine(s) where you can run your applications with Dapr. Dapr provides the capability to run on machines in "self-hosted" mode. | [Self-hosted mode]({{< ref self-hosted-overview.md >}})
 | Service | A running application or binary. This can refer to your application or to a Dapr application.
 | Sidecar | A program that runs alongside your application as a separate process or container. | [Sidecar pattern](https://docs.microsoft.com/azure/architecture/patterns/sidecar)

daprdocs/content/en/developing-applications/building-blocks/bindings/bindings-overview.md

@@ -24,6 +24,10 @@ For example, with bindings, your microservice can respond to incoming Twilio/SMS
 Bindings are developed independently of Dapr runtime. You can [view and contribute to the bindings](https://github.com/dapr/components-contrib/tree/master/bindings).
 {{% /alert %}}
 
+{{% alert title="Note" color="primary" %}}
+If you are using the HTTP Binding, then it is preferable to use [service invocation]({{< ref service_invocation_api.md >}}) instead. Read [How-To: Invoke Non-Dapr Endpoints using HTTP]({{< ref "howto-invoke-non-dapr-endpoints.md" >}}) for more information.
+{{% /alert %}}
+
 ## Input bindings
 
 With input bindings, you can trigger your application when an event from an external resource occurs. An optional payload and metadata may be sent with the request.

daprdocs/content/en/developing-applications/building-blocks/bindings/howto-bindings.md

@@ -6,6 +6,7 @@ description: "Invoke external systems with output bindings"
 weight: 300
 ---
 
+
 With output bindings, you can invoke external resources. An optional payload and metadata can be sent with the invocation request.
 
 <img src="/images/howto-bindings/kafka-output-binding.png" width=1000 alt="Diagram showing bindings of example service">

daprdocs/content/en/developing-applications/building-blocks/service-invocation/howto-invoke-non-dapr-endpoints.md

@@ -0,0 +1,92 @@
+---
+type: docs
+title: "How-To: Invoke Non-Dapr Endpoints using HTTP"
+linkTitle: "How-To: Invoke Non-Dapr Endpoints"
+description: "Call Non-Dapr endpoints from Dapr applications using service invocation"
+weight: 2000
+---
+
+This article demonstrates how to call a non-Dapr endpoint using Dapr over HTTP.
+
+Using Dapr's service invocation API, you can communicate with endpoints that either use or do not use Dapr. Using Dapr to call endpoints that do not use Dapr not only provides a consistent API, but also the following [Dapr service invocation]({{< ref service-invocation-overview.md >}}) benefits:
+
+- Ability to apply resiliency policies
+- Call observability with tracing & metrics
+- Security access control through scoping
+- Ability to utilize middleware pipeline components
+- Service discovery
+- Authentication through the use of headers
+
+## HTTP service invocation to external services or non-Dapr endpoints
+Sometimes you need to call a non-Dapr HTTP endpoint. For example:
+- You may choose to only use Dapr in part of your overall application, including brownfield development
+- You may not have access to the code to migrate an existing application to use Dapr
+- You need to call an external HTTP service.
+
+By defining an `HTTPEndpoint` resource, you declaratively define a way to interact with a non-Dapr endpoint. You then use the service invocation URL to invoke non-Dapr endpoints. Alternatively, you can place a non-Dapr Fully Qualified Domain Name (FQDN) endpoint URL directly into the service invocation URL.
+
+### Order of precedence between HttpEndpoint, FQDN URL, and appId
+When using service invocation, the Dapr runtime follows a precedence order:
+
+1. Is this a named `HTTPEndpoint` resource?
+2. Is this an FQDN URL with an`http://` or `https://` prefix?
+3. Is this an `appID`?
+
+## Service invocation and non-Dapr HTTP endpoint
+The diagram below is an overview of how Dapr's service invocation works when invoking non-Dapr endpoints.
+
+<img src="/images/service-invocation-overview-non-dapr-endpoint.png" width=800 alt="Diagram showing the steps of service invocation to non-Dapr endpoints">
+
+1. Service A makes an HTTP call targeting Service B, a non-Dapr endpoint. The call goes to the local Dapr sidecar.
+2. Dapr discovers Service B's location using the `HTTPEndpoint` or FQDN URL.
+3. Dapr forwards the message to Service B.
+4. Service B runs its business logic code.
+5. Service B sends a response to Service A's Dapr sidecar.
+6. Service A receives the response.
+
+## Using an HTTPEndpoint resource or FQDN URL for non-Dapr endpoints
+There are two ways to invoke a non-Dapr endpoint when communicating either to Dapr applications or non-Dapr applications. A Dapr application can invoke a non-Dapr endpoint by providing one of the following:
+
+- A named `HTTPEndpoint` resource, including defining an `HTTPEndpoint` resource type. See the [HTTPEndpoint reference]({{< ref httpendpoints-reference.md >}}) guide for an example.
+
+    ```sh
+    localhost:3500/v1.0/invoke/<HTTPEndpoint-name>/method/<my-method>
+    ```
+
+    For example, with an `HTTPEndpoint` resource called "palpatine" and a method called "Order66", this would be:
+    ```sh
+    curl http://localhost:3500/v1.0/invoke/palpatine/method/order66
+    ```
+
+- A FQDN URL to the non-Dapr endpoint.
+
+    ```sh
+    localhost:3500/v1.0/invoke/<URL>/method/<my-method>
+    ```
+
+    For example, with an FQDN resource called `https://darthsidious.starwars`, this would be:
+    ```sh
+    curl http://localhost:3500/v1.0/invoke/https://darthsidious.starwars/method/order66
+    ```
+
+### Using appId when calling Dapr enabled applications
+AppIDs are always used to call Dapr applications with the `appID` and `my-method. Read the [How-To: Invoke services using HTTP]({{< ref howto-invoke-discover-services.md >}}) guide for more information. For example:
+
+```sh
+localhost:3500/v1.0/invoke/<appID>/method/<my-method>
+```
+```sh
+curl http://localhost:3602/v1.0/invoke/orderprocessor/method/checkout
+```
+
+## Related Links
+
+- [HTTPEndpoint reference]({{< ref httpendpoints-reference.md >}})
+- [Service invocation overview]({{< ref service-invocation-overview.md >}})
+- [Service invocation API specification]({{< ref service_invocation_api.md >}})
+
+## Community call demo
+Watch this [video](https://youtu.be/BEXJgLsO4hA?t=364) on how to use service invocation to call non-Dapr endpoints.
+<div class="embed-responsive embed-responsive-16by9">
+<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/BEXJgLsO4hA?t=364" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+</div>

daprdocs/content/en/developing-applications/building-blocks/service-invocation/service-invocation-overview.md

@@ -25,7 +25,7 @@ Dapr uses a sidecar architecture. To invoke an application using Dapr:
 - Each application communicates with its own instance of Dapr. 
 - The Dapr instances discover and communicate with each other.
 
-The diagram below is an overview of how Dapr's service invocation works.
+The diagram below is an overview of how Dapr's service invocation works between two Dapr-ized applications.
 
 <img src="/images/service-invocation-overview.png" width=800 alt="Diagram showing the steps of service invocation">
 
@@ -38,8 +38,10 @@ The diagram below is an overview of how Dapr's service invocation works.
 6. Dapr forwards the response to Service A's Dapr sidecar.
 7. Service A receives the response.
 
+You can also call non-Dapr HTTP endpoints using the service invocation API. For example, you may only use Dapr in part of an overall application, may not have access to the code to migrate an existing application to use Dapr, or simply need to call an external HTTP service. Read ["How-To: Invoke Non-Dapr Endpoints using HTTP"]({{< ref howto-invoke-non-dapr-endpoints.md >}}) for more information.
+
 ## Features
-Service invocation provides several features to make it easy for you to call methods between applications.
+Service invocation provides several features to make it easy for you to call methods between applications or to call external HTTP endpoints.
 
 ### HTTP and gRPC service invocation
 - **HTTP**: If you're already using HTTP protocols in your application, using the Dapr HTTP header might be the easiest way to get started. You don't need to change your existing endpoint URLs; just add the `dapr-app-id` header and you're ready to go. For more information, see [Invoke Services using HTTP]({{< ref howto-invoke-discover-services.md >}}). 

daprdocs/content/en/operations/support/support-preview-features.md

@@ -20,6 +20,7 @@ For CLI there is no explicit opt-in, just the version that this was first made a
 | **Pluggable components** | Allows creating self-hosted gRPC-based components written in any language that supports gRPC. The following component APIs are supported: State stores, Pub/sub, Bindings | N/A | [Pluggable components concept]({{<ref "components-concept#pluggable-components" >}})| v1.9  |
 | **Multi-App Run** | Configure multiple Dapr applications from a single configuration file and run from a single command | `dapr run -f` | [Multi-App Run]({{< ref multi-app-dapr-run.md >}}) | v1.10 |
 | **Workflows** | Author workflows as code to automate and orchestrate tasks within your application, like messaging, state management, and failure handling | N/A | [Workflows concept]({{< ref "components-concept#workflows" >}})| v1.10  |
+| **Service invocation for non-Dapr endpoints** | Allow the invocation of non-Dapr endpoints by Dapr using the [Service invocation API]({{< ref service_invocation_api.md >}}). Read ["How-To: Invoke Non-Dapr Endpoints using HTTP"]({{< ref howto-invoke-non-dapr-endpoints.md >}}) for more information. | N/A | [Service invocation API]({{< ref service_invocation_api.md >}}) | v1.11  |
 
 ### Streaming for HTTP service invocation
 

daprdocs/content/en/reference/api/metadata_api.md

@@ -6,7 +6,7 @@ description: "Detailed documentation on the Metadata API"
 weight: 1100
 ---
 
-Dapr has a metadata API that returns information about the sidecar allowing runtime discoverability. The metadata endpoint returns a list of the components loaded, the activated actors (if present) and attributes with information attached.
+Dapr has a metadata API that returns information about the sidecar allowing runtime discoverability. The metadata endpoint returns a list of the resources (components and HttpEndpoints loaded), the activated actors (if present), and attributes with information attached.
 
 ## Components
 Each loaded component provides its name, type and version and also information about supported features in the form of component capabilities. 
@@ -17,6 +17,9 @@ Component type | Capabilities
 State Store    | ETAG, TRANSACTION, ACTOR, QUERY_API
 Binding        | INPUT_BINDING, OUTPUT_BINDING
 
+## HTTPEndpoints
+Each loaded `HttpEndpoint` provides a name to easily identify the Dapr resource associated with the runtime.
+
 ## Attributes
 
 The metadata API allows you to store additional attribute information in the format of key-value pairs. These are ephemeral in-memory and are not persisted if a sidecar is reloaded. This information should be added at the time of a sidecar creation, for example, after the application has started. 

daprdocs/content/en/reference/api/service_invocation_api.md

@@ -6,17 +6,29 @@ description: "Detailed documentation on the service invocation API"
 weight: 100
 ---
 
-Dapr provides users with the ability to call other applications that have unique ids.
-This functionality allows apps to interact with one another via named identifiers and puts the burden of service discovery on the Dapr runtime.
+Dapr provides users with the ability to call other applications that are using Dapr with a unique named identifier (appId), or HTTP endpoints that are not using Dapr.
+This allows applications to interact with one another via named identifiers and puts the burden of service discovery on the Dapr runtime.
 
-## Invoke a method on a remote dapr app
+## Invoke a method on a remote Dapr app
 
 This endpoint lets you invoke a method in another Dapr enabled app.
 
 ### HTTP Request
 
 ```
-PATCH/POST/GET/PUT/DELETE http://localhost:<daprPort>/v1.0/invoke/<appId>/method/<method-name>
+PATCH/POST/GET/PUT/DELETE http://localhost:<daprPort>/v1.0/invoke/<appID>/method/<method-name>
+```
+
+## Invoke a method on a non-Dapr endpoint
+
+This endpoint lets you invoke a method on a non-Dapr endpoint using an `HTTPEndpoint` resource name, or a Fully Qualified Domain Name (FQDN) URL.
+
+### HTTP Request
+
+```
+PATCH/POST/GET/PUT/DELETE http://localhost:<daprPort>/v1.0/invoke/<HTTPEndpoint name>/method/<method-name>
+
+PATCH/POST/GET/PUT/DELETE http://localhost:<daprPort>/v1.0/invoke/<FQDN URL>/method/<method-name>
 ```
 
 ### HTTP Response codes
@@ -38,7 +50,9 @@ XXX  | Upstream status returned
 Parameter | Description
 --------- | -----------
 daprPort | the Dapr port
-appId | the App ID associated with the remote app
+appID | the App ID associated with the remote app
+HTTPEndpoint name | the HTTPEndpoint resource associated with the external endpoint
+FQDN URL | Fully Qualified Domain Name URL to invoke on the external endpoint
 method-name | the name of the method or url to invoke on the remote app
 
 > Note, all URL parameters are case-sensitive.
@@ -65,9 +79,9 @@ Within the body of the request place the data you want to send to the service:
 
 ### Request received by invoked service
 
-Once your service code invokes a method in another Dapr enabled app, Dapr will send the request, along with the headers and body, to the app on the `<method-name>` endpoint.
+Once your service code invokes a method in another Dapr enabled app or non-Dapr endpoint, Dapr sends the request, along with the headers and body, on the `<method-name>` endpoint.
 
-The Dapr app being invoked will need to be listening for and responding to requests on that endpoint.
+The Dapr app or non-Dapr endpoint being invoked will need to be listening for and responding to requests on that endpoint.
 
 ### Cross namespace invocation
 
@@ -120,5 +134,19 @@ In case you are invoking `mathService` on a different namespace, you can use the
 
 In this URL, `testing` is the namespace that `mathService` is running in.
 
+#### Non-Dapr Endpoint Example
+
+If the `mathService` service was a non-Dapr application, then it could be invoked using service invocation via an `HTTPEndpoint`, as well as a Fully Qualified Domain Name (FQDN) URL.
+
+```shell
+curl http://localhost:3500/v1.0/invoke/mathHTTPEndpoint/method/add \
+  -H "Content-Type: application/json"
+  -d '{ "arg1": 10, "arg2": 23}'
+
+curl http://localhost:3500/v1.0/invoke/http://mathServiceURL.com/method/add \
+  -H "Content-Type: application/json"
+  -d '{ "arg1": 10, "arg2": 23}'
+```
+
 ## Next Steps
 - [How-To: Invoke and discover services]({{< ref howto-invoke-discover-services.md >}})

daprdocs/content/en/reference/components-reference/supported-bindings/http.md

@@ -7,6 +7,10 @@ aliases:
   - "/operations/components/setup-bindings/supported-bindings/http/"
 ---
 
+## Alternative
+
+The [service invocation API]({{< ref service_invocation_api.md >}}) allows for the invocation of non-Dapr HTTP endpoints and is the recommended approach. Read ["How-To: Invoke Non-Dapr Endpoints using HTTP"]({{< ref howto-invoke-non-dapr-endpoints.md >}}) for more information.
+
 ## Setup Dapr component
 
 ```yaml

daprdocs/content/en/reference/resource-specs/_index.md

@@ -0,0 +1,7 @@
+---
+type: docs
+title: "Dapr resource specs"
+linkTitle: "Resource specs"
+description: "Detailed information and specifications on Dapr resources"
+weight: 500
+---

daprdocs/content/en/reference/resource-specs/httpendpoints-reference.md

@@ -0,0 +1,41 @@
+---
+type: docs
+title: "HTTPEndpoint spec"
+linkTitle: "HTTPEndpoint spec"
+description: "The HTTPEndpoint resource spec"
+weight: 300
+aliases:
+  - "/operations/httpEndpoints/"
+---
+
+The `HTTPEndpoint` is a Dapr resource that is used to enable the invocation of non-Dapr endpoints from a Dapr application.
+
+## HTTPEndpoint format
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: HTTPEndpoint
+metadata:
+  name: <NAME>  
+spec:
+  version: v1alpha1
+  baseUrl: <REPLACE-WITH-BASEURL> # Required. Use "http://" or "https://" prefix.
+  headers: # Optional
+  - name: <REPLACE-WITH-A-HEADER-NAME>
+    value: <REPLACE-WITH-A-HEADER-VALUE>
+  - name: <REPLACE-WITH-A-HEADER-NAME>
+    secretKeyRef:
+      name: <REPLACE-WITH-SECRET-NAME>
+      key: <REPLACE-WITH-SECRET-KEY>
+scopes: # Optional
+  - <REPLACE-WITH-SCOPED-APPIDS>
+auth: # Optional
+  secretStore: <REPLACE-WITH-SECRETSTORE>
+```
+
+## Spec fields
+
+| Field              | Required | Details | Example |
+|--------------------|:--------:|---------|---------|
+| baseUrl            | Y        | Base URL of the non-Dapr endpoint | `"https://api.github.com"`, `"http://api.github.com"`
+| headers            | N        | HTTP request headers for service invocation | `name: "Accept-Language" value: "en-US"` <br/> `name: "Authorization" secretKeyRef.name: "my-secret" secretKeyRef.key: "myGithubToken" `