Quickstart: State Management

This quickstart showcases how to enable stateful data persistence using the State API.

Prerequisites

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

Python

• Diagrid CLI
• Git
• Python 3.11+

.NET

• Diagrid CLI
• Git
• .NET 8.0+

JavaScript

• Diagrid CLI
• Git
• Node.JS LTS

Java

• Diagrid CLI
• Git
• Java 11.0+: OracleJDK or OpenJDK
• Apache Maven 3.9.5+

Log in to Catalyst

Authenticate to Diagrid Catalyst using the following command:

diagrid login 

Confirm your organization and user details are correct:

diagrid whoami

Deploy quickstart project

Create a project and bootstrap the necessary resources to begin developing locally with the State API. This command:

✔️ Creates a new Catalyst project
✔️ Deploys a Diagrid KV Store instance
✔️ Creates an App ID for the application invoking the State API
✔️ Clones a quickstart application to your machine
✔️ Scaffolds a dev config file to run the quickstart code with the necessary Catalyst connectivity info

Python

diagrid project quickstart --type state --language python

.NET

diagrid project quickstart --type state --language csharp

JavaScript

diagrid project quickstart --type state --language javascript

Java

diagrid project quickstart --type state --language java

After the command executes successfully, the CLI will output the contents of your newly created project including an App ID called order-app and a Diagrid KV Store called kvstore.

Run sample application

To run the quickstart code locally, you can use the diagrid dev start command. This command:

• Launches the local quickstart code: Locates the code directory using the value specified for workDir and launches the code using the app command inputs
• Injects environment variables: Configures the Dapr client to talk to Catalyst using the order-app App ID API token
• Streams application logs: Displays connectivity logs along with real-time app feedback directly in the terminal to make API testing simple

For additional details on the Catalyst local development experience, read Develop Locally with Catalyst APIs.

Python

Install python dependencies in a virtual environment.

note

This quickstart uses the venv module to create the virtual environment. Please feel free to adapt if you prefer to use conda, pipenv, or another alternative.

python -m venv venv

MacOS

If you are using MacOS, start the virtual environment with the following command:

source venv/bin/activate

tip

Don't forget to close your virtual environment with deactivate when done with the quickstart

Linux

If you are using Linux, start the virtual environment with the following command:

source venv/bin/activate

tip

Don't forget to close your virtual environment with deactivate when done with the quickstart

Windows

If you are using PowerShell on Windows, start the virtual environment with the following command:

venv/Scripts/Activate.ps1

If you are using the Command Prompt on Windows, start the virtual environment with the following command:

venv/Scripts/activate.bat

tip

If running in the Windows Command Prompt, don't forget to close your virtual environment with venv/Scripts/deactivate.bat when done with the quickstart

Install the python app requirements:

pip install -r requirements.txt

.NET

Install .NET dependencies.

dotnet build

JavaScript

Install node dependencies.

npm ci

Java

Install maven dependencies.

mvn clean install

Run the diagrid dev start command:

diagrid dev start

Call the State API

With the quickstart application running, use the curl commands below or take advantage of the test.rest file in the root folder of the repo powered by the VS Code REST Client extension to trigger requests from the app to the Dapr State API hosted by Catalyst.

Store state

Open a new terminal and execute the following curl command to save a state item to the Diagrid KV store:

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

Retrieve state

Confirm the state item was saved successfully by retrieving the state:

curl -i -X GET http://localhost:5001/order/1

Delete state

Delete the state item using the below command:

curl -i -X DELETE http://localhost:5001/order/1

After running the above commands, the local app logs should indicate an order was saved, retrieved and deleted. You can confirm this by viewing the Catalyst API logs.

To stop the application use CTL-C or run the following:

diagrid dev stop

Clean up resources

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

diagrid appid delete order-app 

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