Getting Started with StateSet API

Welcome to StateSet API! This guide will help you get up and running with our comprehensive backend system for order management, inventory control, returns processing, and more.

Prerequisites
Installation
Configuration
Database Setup
Building the Project
Running the API
Development Workflow
Testing
API Documentation
Troubleshooting

Prerequisites

Before you begin, ensure you have the following installed on your development machine:

Required Software

Rust (latest stable version)

# Install Rust via rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Verify installation
rustc --version
cargo --version

Database (Choose one):

SQLite (default for development)
- Automatically created when running the API

PostgreSQL 14+ (recommended for production)

# macOS
brew install postgresql@14

# Ubuntu/Debian
sudo apt-get install postgresql-14

# Verify installation
psql --version

Optional Tools

Redis (for caching, optional)

# macOS
brew install redis

# Ubuntu/Debian
sudo apt-get install redis-server

Protocol Buffer Compiler (for gRPC development)

# macOS
brew install protobuf

# Ubuntu/Debian
sudo apt-get install protobuf-compiler

Installation

Clone the Repository

git clone https://github.com/stateset/stateset-api.git
cd stateset-api

Install Rust Dependencies

# This will download and compile all dependencies
cargo fetch

Configuration

StateSet API uses environment variables and configuration files for setup.

1. Environment Variables (.env)

Create a .env file in the project root:

cp .env.example .env

Edit .env with your configuration:

# Database Configuration
DATABASE_URL=sqlite:stateset.db?mode=rwc  # For SQLite (development)
# DATABASE_URL=postgres://username:password@localhost/stateset_db  # For PostgreSQL

# JWT Configuration
JWT_SECRET=your_secure_jwt_secret_key_change_in_production
JWT_EXPIRATION=3600              # 1 hour in seconds
JWT_REFRESH_EXPIRATION=604800    # 7 days in seconds

# Server Configuration
PORT=8080
HOST=0.0.0.0
APP_ENV=development

# Logging
RUST_LOG=stateset_api=debug,tower_http=debug,sea_orm=debug,info

# Optional: Redis (if using caching)
# REDIS_URL=redis://localhost:6379

2. Configuration File (config/default.toml)

The TOML configuration file provides additional settings:

# Database
database_url = "sqlite:stateset.db?mode=rwc"
auto_migrate = true  # Automatically run migrations on startup

# Server
host = "0.0.0.0"
port = 8080

# Cache (optional)
[cache]
cache_type = "memory"  # or "redis" if Redis is configured
capacity = 1000
default_ttl_secs = 300

Database Setup

SQLite (Default for Development)

SQLite requires no additional setup. The database file will be created automatically when you first run the application.

PostgreSQL (Production)

Create Database

# Connect to PostgreSQL
psql -U postgres

# Create database and user
CREATE DATABASE stateset_db;
CREATE USER stateset_user WITH ENCRYPTED PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE stateset_db TO stateset_user;
\q

Update DATABASE_URL in .env

DATABASE_URL=postgres://stateset_user:your_password@localhost/stateset_db

Running Migrations

Migrations are handled automatically on startup if auto_migrate = true in your config. To run them manually:

# Using the migration binary
cargo run --bin migration

# Or using SQLx CLI (if installed)
sqlx migrate run

Building the Project

StateSet API provides several build options:

Development Build

# Quick build for development
cargo build

# Or using the Makefile
make build

Release Build (Optimized)

# Optimized build for production
cargo build --release

# Or using the Makefile
make build-release

Build Specific Components

# Build only the main API server
cargo build --bin stateset-api

# Build the minimal server (lightweight version)
cargo build --bin minimal-server

# Build the gRPC server
cargo build --bin grpc-server

# Build performance testing tools
cargo build --bin orders-bench
cargo build --bin orders-mock-server

Running the API

Main API Server

# Run in development mode
cargo run

# Or using the Makefile
make run

# Run with specific binary
cargo run --bin stateset-api

# Run release build
./target/release/stateset-api

Alternative Servers

# Run minimal server (lightweight, fewer features)
cargo run --bin minimal-server

# Run gRPC server
cargo run --bin grpc-server

# Run mock server for testing
cargo run --bin orders-mock-server

Verify the Server is Running

# Health check
curl http://localhost:8080/health

# Should return:
# {"status":"healthy"}

Development Workflow

1. Code Organization

src/
├── commands/        # Write operations (Command pattern)
├── queries/         # Read operations (Query pattern)
├── handlers/        # HTTP request handlers
├── services/        # Business logic
├── entities/        # Database entities (SeaORM)
├── models/          # Domain models
├── repositories/    # Data access layer
└── main.rs         # Application entry point

2. Adding New Features

Create Command/Query

// src/commands/orders/create_order_command.rs
pub struct CreateOrderCommand {
    pub customer_id: Uuid,
    pub items: Vec<OrderItem>,
}

Implement Service

// src/services/orders.rs
impl OrderService {
    pub async fn create_order(&self, cmd: CreateOrderCommand) -> Result<Order> {
        // Business logic here
    }
}

Add Handler

// src/handlers/orders.rs
pub async fn create_order(
    State(state): State<AppState>,
    Json(payload): Json<CreateOrderRequest>,
) -> Result<Json<OrderResponse>> {
    // Handle HTTP request
}

3. Hot Reloading (Development)

Use cargo-watch for automatic recompilation:

# Install cargo-watch
cargo install cargo-watch

# Run with auto-reload
cargo watch -x run

4. Code Quality Tools

# Format code
cargo fmt

# Run linter
cargo clippy

# Check for security issues
cargo audit

# Generate documentation
cargo doc --open

Testing

Running Tests

# Run all tests
cargo test

# Run specific test
cargo test test_create_order

# Run tests with output
cargo test -- --nocapture

# Run tests with backtrace
RUST_BACKTRACE=1 cargo test

# Run integration tests only
cargo test --test '*'

# Using Makefile
make test

Writing Tests

#[cfg(test)]
mod tests {
    use super::*;
    
    #[tokio::test]
    async fn test_create_order() {
        // Test implementation
        let service = OrderService::new(db_pool);
        let order = service.create_order(cmd).await.unwrap();
        assert_eq!(order.status, "pending");
    }
}

Performance Testing

# Run order throughput benchmark
cargo run --bin orders-bench

# Start mock server for load testing
cargo run --bin orders-mock-server

# In another terminal, run benchmarks
ab -n 1000 -c 10 http://localhost:8080/orders

API Documentation

REST API Endpoints

The API provides comprehensive endpoints for all operations:

Authentication

POST /auth/register - Register new user
POST /auth/login - Login and receive JWT token
POST /auth/refresh - Refresh JWT token

Orders

GET /orders - List all orders
GET /orders/:id - Get order by ID
POST /orders - Create new order
PUT /orders/:id - Update order
DELETE /orders/:id - Delete order
POST /orders/:id/cancel - Cancel order
POST /orders/:id/hold - Put order on hold

Inventory

GET /inventory - Get inventory levels
POST /inventory/adjust - Adjust inventory
POST /inventory/allocate - Allocate inventory
POST /inventory/reserve - Reserve inventory

Returns

POST /returns - Create return
GET /returns/:id - Get return details
POST /returns/:id/approve - Approve return
POST /returns/:id/reject - Reject return

OpenAPI/Swagger Documentation

When running in development mode, interactive API documentation is available at:

http://localhost:8080/swagger-ui

gRPC API

For gRPC clients, proto files are located in proto/ directory. Generate client code:

# Generate Rust code from proto files
cargo build  # Automatically generates during build

# For other languages, use protoc directly
protoc --go_out=. --go-grpc_out=. proto/*.proto

Troubleshooting

Common Issues and Solutions

1. Build Errors

# Clear build cache
cargo clean

# Update dependencies
cargo update

# Check for specific errors
cargo build 2>&1 | tee build_errors.log

2. Database Connection Issues

# Test database connection
psql $DATABASE_URL -c "SELECT 1"

# For SQLite, check file permissions
ls -la stateset.db

# Reset database
rm stateset.db  # For SQLite
# OR
DROP DATABASE stateset_db; CREATE DATABASE stateset_db;  # For PostgreSQL

3. Port Already in Use

# Find process using port 8080
lsof -i :8080

# Kill the process
kill -9 <PID>

# Or use a different port
PORT=3000 cargo run

4. Migration Failures

# Reset migrations
cargo run --bin migration -- reset

# Run migrations step by step
cargo run --bin migration -- up

Debugging

# Enable debug logging
RUST_LOG=debug cargo run

# Enable backtrace for errors
RUST_BACKTRACE=1 cargo run

# Use debugger (VS Code or IntelliJ Rust)
# Add breakpoints and run in debug mode

Performance Issues

# Profile the application
cargo build --release
valgrind --tool=callgrind ./target/release/stateset-api

# Check database queries
RUST_LOG=sea_orm=debug cargo run

# Monitor resource usage
htop  # While application is running

Next Steps

Explore the Codebase
- Review src/handlers/ for API endpoints
- Check src/services/ for business logic
- Look at tests/ for usage examples
Customize Configuration
- Modify config/default.toml for your needs
- Set up proper JWT secrets for security
- Configure database connections
Set Up Development Environment
- Install VS Code with rust-analyzer extension
- Configure your IDE for Rust development
- Set up pre-commit hooks for code quality
Learn the Architecture
- Read about CQRS pattern used in commands/queries
- Understand the event-driven architecture
- Review the domain models and entities
Contribute
- Check out open issues on GitHub
- Read CONTRIBUTING.md for guidelines
- Join our community discussions

Getting Help

Documentation: Full docs at docs.stateset.com
GitHub Issues: github.com/stateset/stateset-api/issues
Discord Community: Join our Discord for real-time help
API Reference: Check /swagger-ui when running locally

License

StateSet API is licensed under the MIT License. See LICENSE for details.

Happy coding! Welcome to the StateSet community! 🚀

Get started

Platform

StateSet One

StateSet Response

StateSet ResponseCX

StateSet iCommerce

StateSet Commerce

StateSet Sandbox

StateSet ACP

StateSet Sequencer

StateSet UCP

StateSet Cloud

Tools

Documentation Index

​Getting Started with StateSet API

​Table of Contents

​Prerequisites

​Required Software

​Optional Tools

​Installation

​Configuration

​1. Environment Variables (.env)

​2. Configuration File (config/default.toml)

​Database Setup

​SQLite (Default for Development)

​PostgreSQL (Production)

​Running Migrations

​Building the Project

​Development Build

​Release Build (Optimized)

​Build Specific Components

​Running the API

​Main API Server

​Alternative Servers

​Verify the Server is Running

​Development Workflow

​1. Code Organization

​2. Adding New Features

​3. Hot Reloading (Development)

​4. Code Quality Tools

​Testing

​Running Tests

​Writing Tests

​Performance Testing

​API Documentation

​REST API Endpoints

​Authentication

​Orders

​Inventory

​Returns

​OpenAPI/Swagger Documentation

​gRPC API

​Troubleshooting

​Common Issues and Solutions

​1. Build Errors

​2. Database Connection Issues

​3. Port Already in Use

​4. Migration Failures

​Debugging

​Performance Issues

​Next Steps

​Getting Help

​License