Skip to main content

Catalyst APIs

Diagrid Catalyst is a suite of hosted APIs that conform to the Dapr open-source standard. Dapr has 10 different building block APIs for addressing common challenges in building resilient microservices applications, and Catalyst provides a subset of these completely managed for you.

The Dapr open-source project is backed by a vibrant community and has been donated to the Cloud Native Computing Foundation (CNCF) where it is working towards graduation status.

When developing with open-source Dapr, you can access the APIs using native HTTP and gRPC clients or take advantage of the Dapr SDKs in the language of your choice. The same is true for Catalyst which allows for an improved local development experience by not requiring any additional Dapr dependencies to be installed locally. For application hosting, the Catalyst APIs can be accessed from any location, across all clouds and compute platforms. With Catalyst providing the standardized API surface and cross-cutting concerns such as security, resiliency and observability, there is no need to install Dapr on your hosting platform.

Catalyst provides the following APIs:

  • Pub/Sub API: A loosely coupled messaging pattern where "publisher apps" publish messages to a topic, to which "subscriber apps" subscribe.
  • Key/Value API: Persistent key/value store access and management.
  • Request/Reply API: Enables applications to discover and invoke endpoints across clouds, regions and compute platforms using built-in identity.
  • Workflow API: Enables long-running, stateful and fault-tolerant applications or data flows that orchestrate business processes.
  • Bindings API: Invoke external services from your application or trigger application logic based on events from an external cloud or on-premises service.

Pub/Sub API​

The Publish/Subscribe (Pub/Sub) API enables services to communicate with each other asynchronously using messages for event-driven architectures. This pattern is especially useful when you need to decouple microservices from one another. There are two services involved:

  • The publisher service, writes messages to a topic, unaware which application(s) will receive them.
  • The subscriber service, subscribes to the topic and receives messages, unaware which service produced these messages.

For this API, a message broker is used to deliver the messages from the publisher service to all subscribing services. To use the pub/sub API you can provision a Diagrid managed message broker or bring your own external infrastructure by creating a new Pub/sub connection.

Pub/sub API resources:

Key/Value API​

The Key/Value API is used to save, read, and query key/value pairs in an underlying state store. Using a key/value store allows you to build stateful, persistent applications that save and retrieve their state for various business logic scenarios. To use the Key/Value API, you can provision a Diagrid managed state store or bring your own external infrastructure by creating a new key/value connection.

By default, all state keys are prefixed with the application's App ID before the state key <App ID>||<state key> and are accessible only by the respective application. To share application state across App IDs (and thus applications), set the keyPrefix value on the infrastructure connection. Supported key prefix strategies are documented here.

Key/Value API resources:

Request/Reply API​

The Request/Reply API allows your applications to discover and communicate with other applications using standard gRPC or HTTP protocols. This pattern is useful when two services are tightly coupled and need to communicate synchronously. Catalyst enables an application to discover and invoke an endpoint across any cloud or compute platform in a standardized, resilient, secure, and observable way.

This API does not depend on the existence of any Catalyst infrastructure connections, but rather requires an invocable App ID which is configured with an Application Endpoint.

Request/reply API resources:

Workflow API​

Catalyst Workflows provides an easy way to express business processes and integrations as code, in a reliable, fault-tolerant way. Workflows are stateful, allowing for writing durable, long-running applications with the ability to start, pause and stop executions and then pick back up without missing a step in the process. Catalyst provides the workflow engine which takes care of the orchestration of the workflow, and your code only needs to contain the business logic steps.

To develop a Catalyst Workflow, you are required to use the Dapr Workflow Authoring SDK in your application code. On application start-up the SDK internally connects to Catalyst using a gRPC stream. This registers the workflow with the Catalyst-managed Dapr workflow engine and any workflow activities, or tasks that workflows can schedule. All interactions happen over this single gRPC channel and are initiated by the application, meaning your application doesn’t need to open an inbound port (App Connections). Read Dapr Workflow Architecture for additional details.

To start, pause, stop and get information about your Catalyst Workflows, use the Workflow Management APIs. These HTTP API calls allow you to interact directly with workflows or use them in other applications such as console apps.

Catalyst Workflows save their state incrementally by appending workflow state to a read-only history log. The workflow state store can be managed by Catalyst or use a state connection to a transactional state store of your choice. Only a single state connection within a Catalyst project can be set as the workflow state store. The Catalyst web console also provides a visualization on top of workflows, allowing for greater insights into the current status, parameters, history and output of each workflow execution.

In summary, to use the Workflow API:

  • Configure a workflow store: Enable Managed Workflows on your Catalyst project or set up an external store by creating a state connection with the enableWorkflow metadata property set to true. If you are are using an external state connection, read the current limitations.
  • Author your code using the Dapr Workflow SDK: Follow the instructions in Connect Dapr SDKs to Catalyst APIs to configure the workflow SDK in the language of your choice.
  • Manage the workflow via the Workflow Management APIs: Start, pause and stop workflows using the management APIs.
Catalyst Managed Workflow

It's recommended to enable Catalyst managed workflows for an improved experience with the Workflow APIs.

Workflow API resources:

Bindings API​

The Bindings API is used to trigger running your application code or provides a standard interface to integrate with external systems. The API has the concept of both Input and Output bindings that implement different scenarios:

  • Input bindings: Allow for a specific endpoint to be hit which triggers the execution of your application code.
  • Output bindings: Integrate with an external system to output a custom payload from your application code.

To use the Bindings API, you are required to bring your own external infrastructure by creating a new bindings connection.

Bindings API resources: