Skip to main content

Make your first API request

This guide gets you up and running with the Catalyst Pub/Sub API in minutes using the Diagrid CLI.

Prerequisites​

Before you proceed, ensure you have the following prereqs installed:

Log in​

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 a Catalyst Pub/Sub service.

diagrid project create my-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 my-project

Create App IDs​

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 subscribing app.

diagrid appid create publisher && diagrid appid create subscriber

Create Pub/Sub topic subscription​

With the Diagrid Pub/Sub service in place, the next step is to create a topic subscription through which the subscriber App ID can receive published messages.

Use the following command to ensure all messages sent to the orders topic are routed to the /orders endpoint of the subscription application:

diagrid subscription create pubsub-subscription --component pubsub --topic orders --route /orders --scopes subscriber

Simulate the subscription​

The Diagrid CLI provides a set of commands that allow you to test the Catalyst APIs without deploying applications for the publisher and subscriber App IDs.

Run the command below to simulate the subscription app and listen for events related to the pubsub-subscription topic subscription. The initial setup might take a moment, but subsequent interactions are faster.

diagrid listen --app-id subscriber --subscription pubsub-subscription

This blocking command acts like a local application, logging incoming messages from the specified subscription.

The subscriber App ID shows it is connected to the local terminal when you retrieve the app connection details:

subscriber endpoint

Publish message​

To publish a message to the orders topic, open a new terminal and run the following command:

diagrid call publish orders --component 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 subscriber application to see the incoming message.

local cli pubsub

For experimentation, modify the orderId value and dispatch multiple messages. The subscriber, simulated in the terminal, should promptly log these incoming messages.

You can also see the subscriber on the topic using the Diagrid Pub/Sub service topic explorer:

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 subscriber

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 subscriber App IDs would be connected to external applications.

Next Steps​

To see the API in action from application code, dive into the API quickstarts