Skip to main content

Tutorial: Publish/Subscribe API

This tutorial showcases how to enable the publisher-subscriber pattern between two locally-running applications via the Diagrid Pub/Sub API.

To complete this tutorial you will:

  • Create Diagrid resources required to enable Pub/Sub messaging between two applications
  • Establish a connection between the application services and associated Catalyst App IDs
  • Test the Publish/Subscribe API to ensure messages are successfully published and delivered

Prerequisites​

Before you proceed with the tutorial, ensure you have the appropriate prerequisites installed for the language you would like to target.

Clone the samples repo​

Begin by cloning the samples repository to your local machine with the following command: 

git clone https://github.com/diagridio/catalyst-samples.git

Login to Diagrid Catalyst​

Authenticate to Diagrid Catalyst using the following command:

diagrid login

Confirm your organization and user details are correct:

diagrid whoami

Create Catalyst resources​

In this section, you will create the following resources in your Diagrid account:

  1. A Diagrid project, which acts as a logical container into which Catalyst resources like App IDs, Connections, etc. are deployed.
  2. A Diagrid Pub/Sub Broker, pubsub, which will be used to enable asynchronous messaging between applications.
  3. An App ID, publisher, which will be used by the local publisher app to publish messages to the underlying broker.
  4. A second App ID, consumer and an associated pub/sub subscription which will route published messages to your local consumer app.

Create project​

If you do not have an existing project available within your organization, create a new Catalyst project and deploy the default pub/sub broker.

diagrid project create catalyst-project --deploy-managed-pubsub

If you have a project already available, ensure the managed broker is deployed. If not, you can create it using the following command:

diagrid pubsub create pubsub

To set this project as the default project in the Diagrid CLI, run:

diagrid project use catalyst-project

Create Application Identities​

In Diagrid Catalyst, each application is represented by a remote identity, known as an App ID. An App ID functions as the single point of contact for all interactions between an application and the Catalyst APIs. Before diving into the application code, create two App IDs in Diagrid Catalyst, one to represent the publishing app, and one to represent the subscribing app.

diagrid appid create publisher
diagrid appid create consumer

Create Pub/Sub Topic Subscription​

With the Diagrid Pub/Sub Broker already provisioned in your project, the next step is to create a topic subscription through which the consumer App ID can subscribe to messages sent by the publisher.

Use the following command to ensure all messages sent to the orders topic in the message broker are routed to the /pubsub/neworders endpoint of the consumer application:

diagrid subscription create pubsub-consumer --connection pubsub --topic orders --route /pubsub/neworders --scopes consumer

Connect your applications to Catalyst​

In this section, we will connect our local applications to Catalyst to enable messaging through the Pub/Sub API using Diagrid-managed resources.

Create dev config file​

To easily run your applications and connect them to their respective App IDs using a single command, you can use a Catalyst dev config file. This is a YAML file that will be automatically generated based on the App IDs created in the previous section.

When used with the diagrid dev start command, the dev config file will:

  • Run the publisher and consumer applications with all required environment variables needed to connect the Dapr SDK to Diagrid Catalyst.
  • Create a Local App Connection for the consumer application on the local appPort, which will route all traffic destined for the consumer App ID to the local port where the code is running.

For additional details on using the dev config file, read Develop Locally with Catalyst APIs.

Navigate to the root directory of the csharp app and install all dotnet dependencies.

cd csharp
dotnet build

Set up your local Catalyst development environment by running the following scaffold command:

diagrid dev scaffold

Open the auto-generated YAML file and add or update the publisher App ID section with the following:

  • workDir: current directory
  • env.ASPNETCORE_URLS: the port your application will listen on
  • command: the application run command

In addition, remove the env.appPort. The publisher is making an inbound call to the Catalyst APIs and does not require an app connection to your the local machine.

Important

Ensure you do not overwrite any of the other values in the file during this process. 

  - appId: publisher
    env:
      DAPR_API_TOKEN: <publisher-api-token>
      DAPR_APP_ID: publisher
      DAPR_CLIENT_TIMEOUT_SECONDS: 10
      DAPR_GRPC_ENDPOINT: <grpc-endpoint>
      DAPR_HTTP_ENDPOINT: <http-endpoint>
      ASPNETCORE_URLS: http://localhost:5001
    workDir: .
    command: ["dotnet", "run"]

Similarily, add or update the consumer App ID section with the following:

  • workDir: current directory
  • env.ASPNETCORE_URLS: the port your application will listen on
  • command: the application run command
  • appPort: used to establish an app connection from Catalyst to the locally-running consumer app
  - appId: consumer
    appPort: 5002
    env:
      DAPR_API_TOKEN: <consumer-api-token>
      DAPR_APP_ID: consumer
      DAPR_CLIENT_TIMEOUT_SECONDS: 10
      DAPR_GRPC_ENDPOINT: <grpc-endpoint>
      DAPR_HTTP_ENDPOINT: <http-endpoint>
      ASPNETCORE_URLS: http://localhost:5002
    workDir: .
    command: ["dotnet", "run"]

Run your applications and connect the consumer App ID to the local consumer app using the following command. 

diagrid dev start
tip

Ensure the log Connected App ID "consumer" to localhost:5002 appears before proceeding to the next section.

Interact with Catalyst APIs​

With the applications now successfully running, it's time to test the publisher and consumer App IDs. To kick off the test, post a simple payload to the publisher app which then gets published as a message for the consumer to receive. Use the curl command below or take advantage of the REST Client extension using Visual Studio Code with the test.rest file in the root folder of the repo.

Open a new terminal and execute the following curl command: 

curl -i -X POST http://localhost:5001/pubsub/orders -H "Content-Type: application/json" -d '{"orderId":1}'

Upon successful execution, the publisher app logs should show an indication that a message was successfully published, and the consumer app logs should indicate the message was successfully received.

csharp-pubsub

To stop the applications use CTL-C and to disconnect the local app connection from the consumer App ID run the following: 

diagrid dev stop

Clean up resources​

If you are not going to continue to use this application, you can delete the Catalyst resoures using the following commands:

diagrid appid delete publisher 
diagrid appid delete consumer

If you want to delete the entire Catalyst project, including the managed infrastructure resources, run the diagrid project delete command.

diagrid project delete catalyst-project