Skip to content

Latest commit

 

History

History
299 lines (217 loc) · 10.8 KB

README.md

File metadata and controls

299 lines (217 loc) · 10.8 KB

RustAPI Examples

Rust RustAPI License Cookbook

Production-ready examples demonstrating the full power of RustAPI — the Rust web framework with FastAPI-like developer experience.

📚 Official Resources:

🚀 Why RustAPI?

"Rust Speed. Python Simplicity. AI Efficiency."

Metric RustAPI Actix Axum FastAPI (Python)
Performance ~92k req/s ~105k ~100k ~12k
Developer Experience 🟢 High 🔴 Low 🟡 Medium 🟢 High
Boilerplate Zero High Medium Zero
AI/LLM Native ✅ ❌ ❌ ❌
Type Safety ✅ ✅ ✅ ❌

Key Features

  • 🎯 Zero Boilerplate — RustApi::auto() discovers all routes automatically
  • 📝 Auto Documentation — OpenAPI/Swagger at /docs out of the box
  • ✅ Built-in Validation — #[validate] with detailed error messages
  • 🔐 JWT Authentication — First-class JwtLayer and AuthUser<T> extractor
  • 🤖 AI-First Architecture — TOON format (50-58% token savings), MCP support
  • ⚡ Middleware Stack — Rate limiting, CORS, logging, circuit breaker, and more
  • 🌐 Real-time — WebSocket support with broadcast channels

📋 Prerequisites

Before running these examples, ensure you have:

# Rust 1.70 or later
rustc --version

# Clone the examples repository
git clone https://github.com/Tuntii/rustapi-rs-examples.git
cd rustapi-rs-examples

# Build all examples
cargo build --release

Optional dependencies (for specific examples):

  • Docker — For sqlx-crud (PostgreSQL/SQLite)
  • SQLite — For sqlx-crud local testing

📂 Examples Overview

This repository contains 18 production-ready examples organized by category:

🌟 Getting Started

Example Difficulty Description Key Features
hello-world ⭐ Minimal 20-line API RustApi::auto(), path params, Json response
crud-api ⭐⭐ Complete CRUD operations Validation, pagination, error handling, body limits
proof-of-concept ⭐⭐⭐ Full-featured bookmark manager JWT, CRUD, SSE, modular handlers, Swagger UI

🔐 Authentication & Security

Example Difficulty Description Key Features
auth-api ⭐⭐⭐ JWT authentication system Login/register, JwtLayer, AuthUser<T>, protected routes
rate-limit-demo ⭐⭐ IP-based rate limiting Per-endpoint limits, burst support, 429 handling
middleware-chain ⭐⭐⭐ Custom middleware composition Request ID, timing, auth, middleware ordering
cors-test ⭐⭐ CORS configuration CorsLayer, allowed origins/methods/headers

🗄️ Database Integration

Example Difficulty Description Key Features
sqlx-crud ⭐⭐⭐ SQLx + SQLite/PostgreSQL Connection pooling, transactions, migrations
event-sourcing ⭐⭐⭐⭐ Event sourcing pattern CQRS, domain events, aggregate reconstruction

🤖 AI & LLM Integration

Example Difficulty Description Key Features
toon-api ⭐⭐ Token-optimized responses ToonResponse, content negotiation, token headers
mcp-server ⭐⭐⭐ Model Context Protocol Tool definitions, resource management, AI agents

🌐 Real-time & Web

Example Difficulty Description Key Features
websocket ⭐⭐⭐ WebSocket chat server Broadcast channels, pub/sub, connection management
templates ⭐⭐ Server-side rendering Tera templates, inheritance, static files

🏗️ Advanced Architecture

Example Difficulty Description Key Features
graphql-api ⭐⭐⭐⭐ GraphQL integration async-graphql, queries/mutations, playground
microservices ⭐⭐⭐⭐ API Gateway pattern Service-to-service communication, routing
microservices-advanced ⭐⭐⭐⭐ Service discovery Registry, heartbeat, Docker Compose
phase11-demo ⭐⭐⭐⭐ Advanced middleware Guards, circuit breaker, timeout, logging
serverless-lambda ⭐⭐⭐ AWS Lambda deployment SAM template, cold start optimization

⚠️ Note: serverless-lambda uses AWS Lambda HTTP runtime instead of RustAPI for serverless deployment patterns.

🎯 Feature Coverage Matrix

Feature Examples Using It
RustApi::auto() All examples
Json<T> / JsonResponse crud-api, auth-api, proof-of-concept, graphql-api
#[validate] crud-api, auth-api, proof-of-concept
JwtLayer / AuthUser<T> auth-api, middleware-chain, phase11-demo, proof-of-concept
RateLimitLayer rate-limit-demo, auth-api, cors-test, proof-of-concept
CorsLayer cors-test, middleware-chain, proof-of-concept
ToonResponse toon-api, mcp-server
WebSocket / WsConnection websocket
View<T> / ViewEngine templates
State<T> All examples with shared state
RequestIdLayer middleware-chain, phase11-demo
CircuitBreakerLayer phase11-demo
TimeoutLayer phase11-demo

📊 RustAPI Feature Flags

Each example uses specific Cargo feature flags. See FEATURES.md for detailed documentation.

Feature Flag Purpose Examples
full All features enabled crud-api, phase11-demo
jwt JWT authentication auth-api, middleware-chain, proof-of-concept
cors CORS middleware cors-test, middleware-chain, proof-of-concept
rate-limit Rate limiting rate-limit-demo, auth-api, cors-test, proof-of-concept
toon TOON format for LLMs toon-api, mcp-server
ws WebSocket support websocket
view Template rendering templates
swagger-ui Swagger UI at /docs toon-api

🚀 Quick Start

Running an Example

# Navigate to repository
cd rustapi-rs-examples

# Run any example
cargo run -p hello-world

# Run with debug logging
RUST_LOG=debug cargo run -p crud-api

# Access Swagger documentation (when running)
# http://127.0.0.1:8080/docs

Testing API Endpoints

# Hello World
curl http://127.0.0.1:8080/
curl http://127.0.0.1:8080/hello/RustAPI

# CRUD API
curl http://127.0.0.1:8080/users
curl -X POST http://127.0.0.1:8080/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}'

# Auth API
curl -X POST http://127.0.0.1:8080/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "password"}'

📚 Learning Path

For a structured learning experience, follow our recommended progression in LEARNING_PATH.md:

1. hello-world     → Basic routing, responses
2. crud-api        → Validation, error handling, state management
3. auth-api        → JWT authentication, protected routes
4. middleware-chain → Custom middleware, composition
5. proof-of-concept → Full application architecture

🔗 Cookbook Cross-References

Each example maps to sections in the RustAPI Cookbook:

Example Cookbook Section
hello-world Getting Started → Quickstart
crud-api Recipes → CRUD Resources
auth-api Recipes → JWT Authentication
middleware-chain Recipes → Custom Middleware
sqlx-crud Recipes → Database Integration
websocket Recipes → WebSockets
templates Crates → rustapi-view
toon-api Crates → rustapi-toon

📝 Creating Your Own Example

  1. Create directory: my-example/

  2. Add Cargo.toml:

    [package]
name = "my-example"
version = "0.1.0"
edition = "2021"

[dependencies]
rustapi-rs = { path = "../../crates/rustapi-rs", features = ["full"] }
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }

  3. Create src/main.rs:

    use rustapi_rs::prelude::*;

#[rustapi_rs::get("/")]
async fn index() -> &'static str {
    "Hello from my example!"
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    RustApi::auto().run("127.0.0.1:8080").await
}

  4. Run it:

    cargo run -p my-example

🎯 Roadmap

Coming Soon

  • redis-cache — Redis caching layer
  • sse-events — Server-Sent Events streaming
  • grpc-integration — gRPC + REST hybrid API
  • distributed-tracing — OpenTelemetry integration
  • kubernetes-ready — Health checks, metrics, graceful shutdown

🤝 Contributing

Contributions are welcome! See our Contributing Guide for details.

  1. Fork this repository
  2. Create your example in a new directory
  3. Add comprehensive documentation (README.md)
  4. Submit a pull request

📄 License

This project is licensed under the MIT OR Apache-2.0 license, same as RustAPI.

Built with ❤️ using RustAPI

Framework · Cookbook · Examples · Discussions