Skip to main content

Test Catalyst APIs without application code

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 connections are working successfully
  • Test your connection 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 Request/Reply you will likely want two App IDs: one to represent the caller (invoker/publisher) and one to represent the receiver (invokee/consumer).

If you are testing the Key-Value 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 Inbound API calls via Catalyst API Explorer​

[ Placeholder to add quick blurb on how to test calling APIs from Portal]

Making Inbound API calls using the Catalyst CLI​

Key/Value API: CRUD operations on K/V state​

To test key-value management using an underlying state store from a given App ID, you can use the diagrid call kv command. Keep in mind, there is a requirement that you have an available kv store connection created. This can be a managed connection to the Diagrid Key/Value store, or an external connection to an existing database. If you do not have a k/v store connection available, you can create a Diagrid Key/Value store connection using diagrid kv create kvstore.

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

To test key/value management you can use the following example commands:

diagrid call kv set 1 --value '{"orderId":0}' --connection kvstore --app-id caller 
# Get the value
diagrid call kv get 1 --connection kvstore --app-id caller 
# Delete the value
diagrid call kv delete 1 --connection kvstore --app-id caller

In this case, the caller App ID will perform CRUD operations against the kvstore connection for a kv pair with a key equal to 1.

Bindings API: Testing output bindings​

To test invoking an output binding to an external service from a given App ID, you can use the diagrid call binding post command. Keep in mind, there is a requirement that you have an available output binding connection created. If you do not have an output binding connection available, you can create one using the instructions for creating an external connection.

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

Pub/Sub API: Testing message publish​

To test publishing to an underlying Pub/Sub broker from a given App ID, you can use the diagrid call publish command. Keep in mind, there is a requirement that you have an available Pub/Sub connection created. This can be a managed connection to the Diagrid Pub/Sub broker, or an external connection to an existing broker. If you do not have a Pub/Sub connection available, you can create a Diagrid Pub/Sub connection using diagrid pubsub create pubsub.

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

Example command:

diagrid call publish orders --connection 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 broker connection 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.

Request/Reply API: Test service invocation​

In the case of the Request/Reply API, two App IDs are required. If you want to test invocation with an existing App ID, no further action is required. However, if you do not have a second App ID available, you should use the call command from the calling App ID in conjunction with the listen command for the receiver App ID which is explained [here].

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 API calls using the Catalyst CLI​

In addition to using the CLI to make calls to the Catalyst APIs via an App ID, you can also simulate receiving calls to an App ID. By running the diagrid listen command, you can route outbound calls from Catalyst 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 Request/Reply API

In order to route these outbound requests to your CLI, Catalyst will create an underlying dev 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 swift.

Listen to any incoming call to an App ID​

Running the listen command for a given App ID will route outbound calls from the App ID to your local CLI. This includes message delivery, input binding triggers or inbound request/reply 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 connection 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. consumer).

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

diagrid subscription create pubsub-subscription --connection pubsub --topic orders --route /orders --scopes <consumer-app-id>

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

diagrid listen --app-id <consumer-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 connection. Keep in mind, there is a requirement that you have an available input binding connection created. If you do not have an input binding connection available, you can create one using the instructions for creating an external connection.

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

Request/Reply 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. caller), and another to receive the invocation (ex. receiver).

If you don't have a receiver, you can use the following command to create one: diagrid appid create receiver and listen to outbound requests using diagrid appid listen --app-id receiver --invoke get

In a second console, you can invoke a generic method to test the invocation is received by the mock receiver App ID.

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 receiver.api --app-id caller

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