Connect to Catalyst Project from Dapr SDKs
The Catalyst APIs are Dapr-compatible, meaning they can be invoked using the open-source Dapr SDKs. The Dapr SDKs provide the easiest path to get up and running with the Catalyst APIs from your application code.
Dapr provides stable Client SDKs for the following languages, which can be used to communicate with the Catalyst APIs:
Dapr also provides a set of Workflow SDKs in addition to the client SDKs. Only the Python, .NET, Java and Go SDKs are currently supported for use with the Catalyst Workflow API:
- ✅ .NET Dapr.Workflow 1.12.0+
- ✅ Python dapr-ext-workflow 0.4.1+
- ✅ Java io.dapr.workflows 1.11.0+
- ✅ Go workflow 1.10.0+
- ❌ JavaScript
For requests sent to your applications from Catalyst, you may find it useful to leverage the server extension packages Dapr provides. However, programmatic subscription support via the SDKs are not supported ❌ with the Catalyst Pub/Sub API.
Install the Dapr language SDKS
The below instructions cover how to download the various language SDKs depending on the needs of your application.
- .NET
- Python
- Go
- JavaScript
- Java
Nuget packages are published after every Dapr release and can be found here. Prerequisites: .NET 5+
# Install Dapr client SDK
dotnet add package Dapr.Client
# Install Dapr server SDK
dotnet add package Dapr.AspNetCore
# Install Dapr workflow SDK
dotnet add package Dapr.Workflow
Prerequisites: Python 3.8+
# Install Dapr client SDK
pip3 install dapr
# Install Dapr gRPC AppCallback service extension
pip3 install dapr-ext-grpc
Prerequisites: Go
# Assuming a correctly configured go toolchain
go get "github.com/dapr/go-sdk/client"
Prerequisites: Node LTS or Current
# Install Dapr client SDK
npm install --save @dapr/dapr
Prerequisites:
- JDK 11 or above - the published jars are compatible with Java 8:
- One of the following build tools for Java:
- Maven
- Gradle
For a Maven project, add the following to your pom.xml
file:
<project>
...
<dependencies>
...
<!-- Dapr's core SDK with all features, except Actors. -->
<dependency>
<groupId>io.dapr</groupId>
<artifactId>dapr-sdk</artifactId>
<version>1.12.0</version>
</dependency>
<!-- Dapr's SDK integration with SpringBoot (optional). -->
<dependency>
<groupId>io.dapr</groupId>
<artifactId>dapr-sdk-springboot</artifactId>
<version>1.12.0</version>
</dependency>
...
</dependencies>
...
</project>
For a Gradle project, add the following to your build.gradle
file:
dependencies {
...
// Dapr's core SDK with all features, except Actors.
compile('io.dapr:dapr-sdk:1.12.0')
// Dapr's SDK integration with SpringBoot (optional).
compile('io.dapr:dapr-sdk-springboot:1.12.0')
}
If you are also using Spring Boot, you may run into a common issue where the OkHttp
version that the Dapr SDK uses conflicts with the one specified in the Spring Boot Bill of Materials.
You can fix this by specifying a compatible OkHttp
version in your project to match the version that the Dapr SDK uses:
<dependency>
<groupId>com.squareup.okhttp3</groupId>
<artifactId>okhttp</artifactId>
<version>1.10.0</version>
</dependency>
Configure the Dapr Client
By default, the Dapr SDKs will attempt to connect to a local Dapr process and access the Dapr OSS APIs on http://localhost
without authentication. To configure the SDK to interact with the remote Catalyst APIs, you need set the Dapr host endpoint as your Catalyst project endpoint using one of the environment variables below. These are automatically picked up by the SDKs and enable a seamless experience connecting to the Catalyst APIs.
All Dapr SDKs use the gRPC protocol by default, except for JavaScript, which uses HTTP.
export DAPR_HTTP_ENDPOINT=$(diagrid project get -o json | jq -r '.status.endpoints.http.url')
export DAPR_GRPC_ENDPOINT=$(diagrid project get -o json | jq -r '.status.endpoints.grpc.url')
In addition to configuring the Dapr host endpoint, you will also need to provide your application with the API token of its associated App ID. This API Token will be sent to the Catalyst APIs as the dapr-api-token
request header for authentication and request routing. Below shows an example of retrieving the API token for the App ID, my-appid
.
diagrid appid create my-appid
export DAPR_API_TOKEN=$(diagrid appid get my-appid -o json | jq -r '.status.apiToken')
Most Dapr SDKs will pick up the following environment variables as part of the client build process to connect to Diagrid Catalyst without the need to pass them explicitly to the client constructor.
DAPR_HTTP_ENDPOINT
: Your Catalyst project HTTP endpointDAPR_GRPC_ENDPOINT
: Your Catalyst project gRPC endpointDAPR_API_TOKEN
: The API Token for your application's associated Catalyst App ID
After configuring these environment variables, you can proceed to develop against the Catalyst APIs without any local Dapr dependencies.
- .NET
- Python
- Go
- JavaScript
- Java
When using .NET, a DaprClient
can be configured by invoking methods on the DaprClientBuilder
class before calling .Build()
to create the client.
import Dapr.Client;
var daprClient = new DaprClientBuilder()
.UseJsonSerializerSettings( ... ) // Configure JSON serializer
.Build();
For more details on how to configure and leverage the .NET SDK, visit the Dapr SDK documentation.
from dapr.clients import DaprClient
with DaprClient() as d:
# use the client to invoke Catalyst APIs
For more details on how to configure and leverage the .NET SDK, visit the Dapr SDK documentation.
package main
import (
"fmt"
dapr "github.com/dapr/go-sdk/client"
)
func main() {
client, err := dapr.NewClient()
if err != nil {
panic(fmt.Errorf("error creating connection to catalyst: %w", err))
}
defer client.Close()
// use the client to invoke Catalyst APIs
}
import { DaprClient, DaprServer, HttpMethod, CommunicationProtocolEnum } from "@dapr/dapr";
// Create an HTTP-based Dapr client
const client = new DaprClient({communicationProtocol: CommunicationProtocolEnum.HTTP});
// Create an gRPC-based Dapr client
const daprClient = new DaprClient({communicationProtocol: CommunicationProtocolEnum.GRPC });
import io.dapr.client.DaprClient;
import io.dapr.client.DaprClientBuilder;
try (DaprClient client = (new DaprClientBuilder()).build()){
// use the client to invoke Catalyst APIs
}
Next Steps
For examples on how you can use the Dapr Client with the Catalyst APIs, refer to the Catalyst API Reference documentation.