Quickstart: Asynchronous Publish/Subscribe
This guide gets you up and running with the Catalyst Publish/Subscribe API in minutes using the Diagrid CLI.
Prerequisites
| Requirement | Instructions |
|---|---|
| Diagrid Catalyst Account | Catalyst is currently an early-access product. If you have not already been invited to create an account, join the waitlist to request access. |
| Diagrid CLI | Install the Diagrid CLI |
Log in to Diagrid Catalyst
Authenticate to your Diagrid Catalyst organization using the following command:
diagrid login
Confirm your login was successful:
diagrid whoami
Create a 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 Catalyst, each application workload is represented via a corresponding remote identity, known as an App ID. To test asychronous communication between two applications, two App IDs are required.
Create two App IDs: One to represent the publishing app and another to represent the consuming, or subscribing, app.
diagrid appid create publisher
diagrid appid create consumer
Create Pub/Sub Topic Subscription
With the Diagrid Pub/Sub broker in place, the next step is to create a topic subscription through which the consumer App ID can subscribe to messages.
Use the following command to ensure all messages sent to the orders topic are routed to the /orders endpoint of the consumer application:
diagrid subscription create pubsub-consumer --connection pubsub --topic orders --route /orders --scopes consumer
Simulate the Consumer Application
The Diagrid CLI provides a set of commands that allow you to test the Catalyst APIs without deploying applications for the publisher and consumer App IDs.
Run the command below to simulate the consumer app and listen for events related to the pubsub-consumer topic subscription. The initial setup might take a moment, but subsequent interactions are faster.
diagrid listen --app-id consumer --subscription pubsub-consumer
This blocking command acts as a local consumer application, logging incoming messages from the specified subscription.
Publish Message
To publish a message to the orders topic, open a new terminal and run the following command:
diagrid call publish orders --connection pubsub --data '{"orderId":1}' --app-id publisher
This command, representing the publisher's action, sends a message containing an simple order payload to the orders topic. A successful dispatch will return a 204 status code.
Return to the terminal listening to the consumer application to see the incoming message.
For experimentation, modify the orderId value and dispatch multiple messages. The consumer, simulated in the terminal, should promptly log these incoming messages.
Clean up resources
If you're not going to continue to use these resources, run the following commands to remove them from your project:
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
Summary
In this quickstart, the Diagrid CLI was configured to simulate the sending (publishing) and receiving (consuming) of messages using the Pub/Sub API. In actuality, the publisher and consumer App IDs would be connected to external applications.
Next Steps
To see the API in action from application code, dive into the Pub/Sub API code tutorial