Connect Dapr SDKs to Catalyst APIs

The Catalyst APIs are Dapr-compatible, meaning they can be invoked using the open-source Dapr SDKs. The Dapr SDKs provide the easiest path for you 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:

• ✅ .NET 1.12.0+
• ✅ Python 1.11.0+
• ✅ Java 1.10.0+
• ✅ Javascript 3.2.0+
• ✅ Go 1.9.1+

Dapr also provides a set of Workflow SDKs for .NET, Python and Java. Only the .NET SDK is currently supported for use with the Catalyst Workflow APIs:

• ✅ .NET - Dapr.Workflow 1.12.0+
• ❌ Python
• ❌ Java

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 is not supported when using 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

Nuget packages are published after every Dapr release and can be found here.

Prerequisites: .NET Core 3.1 or .NET 5+

# Install Dapr client SDK
dotnet add package Dapr.Client 

# Install Dapr workflow SDK
dotnet add package Dapr.Workflow

# Install Dapr callback SDK
dotnet add package Dapr.AspNetCore

Python

Prerequisites: Python 3.8+

# Install Dapr client SDK
pip3 install dapr

# Install Dapr gRPC AppCallback service extension
pip3 install dapr-ext-grpc

Go

Prerequisites: Go

# Assuming a correctly configured go toolchain
go get "github.com/dapr/go-sdk/client"

JavaScript

Prerequisites: Node LTS or Current

# Install Dapr client SDK
npm install --save @dapr/dapr

Java

Prerequisites:

• JDK 11 or above - the published jars are compatible with Java 8:
  • AdoptOpenJDK 11 - LTS
  • Oracle's JDK 15
  • Oracle's JDK 11 - LTS
  • OpenJDK
• One of the following build tools for Java:
  • Maven 3.x
  • Gradle 6.x

Maven

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>

Gradle

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.

info

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.

daigrid 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 endpoint
• DAPR_GRPC_ENDPOINT: Your Catalyst project gRPC endpoint
• DAPR_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

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.

Python

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.

Go

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
}

JavaScript

info

In future Dapr JS SDK releases, the Dapr client will automatically pick up the DAPR_API_TOKEN environment variable and will not require explicitly setting daprApiToken.

import { DaprClient, DaprServer, HttpMethod, CommunicationProtocolEnum } from "@dapr/dapr";

// Create an HTTP-based Dapr client after setting env variables
const client = new DaprClient({daprApiToken: daprApiToken, communicationProtocol: CommunicationProtocolEnum.HTTP});

// Create an gRPC-based Dapr client after setting env variables
const daprClient = new DaprClient({daprApiToken: daprApiToken, communicationProtocol: CommunicationProtocolEnum.GRPC });
 

Java

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 Samples GitHub repository or run one of the following tutorials in the language of your choice:

• Publish/Subscribe API
• Key/Value API
• Request/Reply API