Test Catalyst APIs using the Diagrid CLI

There may be times when you want to test the Catalyst APIs by calling an App ID directly without deploying application code. For example, you may want to run a quick test to:

• Ensure your infrastructure components are working successfully
• Test your component scopes are being properly enforced
• Validate a dapr subscription

You can do so one of two ways:

• Using the API explorer in the Diagrid Portal
• Using the Diagrid CLI call and listen commands

The following guide will explain how you can best leverage these clients to test the Catalyst APIs.

Prerequisites

In order to test the various APIs you will need minimally one, and potentially two, App IDs. For example, if you are testing end-to-end Pub/Sub or Service Invocation you will likely want two App IDs: one to represent the caller (client/publisher) and one to represent the receiver (server/subscriber).

If you are testing the State or Binding APIs, you may only need one App ID.

If you do not have existing App IDs you want to use to test behavior, you can create them using the diagrid appid create command.

Making requests via Catalyst API Explorer

The Catalyst API Explorer makes it easy for you to test a subset of the Catalyst APIs directly from the browser.

Making API requests using the Diagrid CLI

State API: CRUD operations on state store

To test state management using an underlying state store, you can use the diagrid call state command.

To use the State API, you must have a state component onboarded to Catalyst. This can be a Diagrid KV store component or an external component connected to an existing database.

If you do not have a state store component available, you can create a Diagrid KV Store using diagrid kv create kvstore, which will generate a default state store component for use with the API.

To test state management you can use the following example commands:

diagrid call kv set 1 --value '{"orderId":0}' --component kvstore --app-id caller 

# Get the value
diagrid call kv get 1 --component kvstore --app-id caller 

# Delete the value
diagrid call kv delete 1 --component kvstore --app-id caller

In this case, the caller App ID is performing CRUD operations against the kvstore component for a key-value pair where the key equals 1.

Bindings API: Testing output bindings

To test invoking an output binding to an external service, you can use the diagrid call binding post command.

To use the Bindings API, you must have an output binding component onboarded to Catalyst. If you do not have an output binding component available, you can create one using the instructions for creating an external component.

diagrid call binding post --component <your-binding-component> --app-id caller --data '{"orderId":0}'

Pub/Sub API: Testing message publish

To test publishing to an underlying Pub/Sub broker, you can use the diagrid call publish command.

To use the Pub/Sub API, you must have a Pub/Sub component onboard to Catalyst. This can be a Diagrid Pub/Sub component or an external component connected to an existing database.

If you want to use these commands to test the component to a broker hosted outside of Diagrid Cloud, you can do so using the instructions for creating an external component.

Example command:

diagrid call publish orders --component pubsub --data '{"orderId":0}' --app-id caller

In this case, the caller App ID will publish a message containing an orderId to the orders topic on the pub/sub component called pubsub. All subscriptions to the pubsub broker on the orders topic should subsequently receive the message. If you want to test a subscription to this topic locally, you can create a mock subscriber.

Service Invocation API: Test service invocation

In the case of the Service Invocation API, two App IDs are required. To test invoking the API, you can use the diagrid call command from the calling App ID in conjunction with the diagrid listen command for App ID receiving the invocation request.

diagrid call invoke post <your-appid>.<method-route> --from caller --data '{"orderId":1}'

To invoke an existing service from the caller App ID, update <your-appid> with the existing App ID name and <method-route> with the method which should receive the invocation call.

Receiving outbound requests using the Diagrid CLI

In addition to using the CLI to make requests to the Catalyst APIs via an App ID, you can also simulate receiving calls to an application endpoint. By running the diagrid listen command, you can route outbound requests from a specific Catalyst App ID to your CLI, which acts as a mock application.

Using the listen command is useful to test the following scenarios without deploying application code:

• Subscribing to messages via the Pub/Sub API
• Triggering an input binding via the Bindings API
• Receiving direct invocations via the Service Invocation API

In order to route these outbound requests to your CLI, Catalyst will create a private network tunnel and set your App ID's app connection endpoint to a port on your local machine. The initial establishment of the local app connection might take a moment, but interating with the APIs afterward will be much faster.

Listen to any incoming call to an App ID

Running the listen command for a given App ID will route outbound requests from its associated App ID to your local CLI. This includes message delivery, input binding triggers or inbound invocation calls.

diagrid listen --app-id your-app-id

Pub/Sub API: Creating mock subscriber

In order to test if a topic subscription to a given Pub/Sub component is valid without deploying the subscribing app, you can use the diagrid listen command.

To test the end-to-end scenario will require two App IDs: one to initiate the publish action (ex. publisher), and another to receive the invocation (ex. subscriber).

The subscribing App ID must have a subscription configured in order for the listen command to function as expected. Replace the value of <subscriber-app-id> with an existing App ID, or a newly created App ID using the diagrid appid create command.

diagrid subscription create pubsub-subscription --component pubsub --topic orders --route /orders --scopes <subscriber-app-id>

After a subscription is created for the subscribing application, run the following command:

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

To trigger a message on the broker, use an existing publisher application or use the diagrid call command to publish a message using the CLI.

Bindings API: Creating mock input binding receiver

To test an input binding trigger for a given App ID, you can use the diagrid listen command, passing in a binding component. Keep in mind, there is a requirement that you have an available input binding component created. If you do not have an input binding component available, you can create one using the instructions for creating an external component.

diagrid listen --app-id receiver --binding <your-binding-component> 

Service Invocation API: Creating mock invocation receiver

In order to test the receipt of an invocation call using the CLI as a mock receiver, you can use the diagrid listen command. This will require two App IDs: one to initiate the invocation (ex. client), and another to receive the invocation (ex. server).

If you don't have an App ID for the mock server application, you can use the following command to create one: diagrid appid create server and listen to outbound requests using diagrid appid listen --app-id server --invoke get

In a second console, you can invoke a generic method to test the invocation is received by the mock server application.

tip

You can pick any name for the mock method to which the invocation is routed, in this example api represents a generic method.

diagrid call invoke get server.api --app-id client

This returns a mock reponse in the listener CLI to simulate the server app receiving the invocation. You can try out other HTTP methods like GET, DELETE, and PUT by changing the get positional argument.