This-RS 🦀

A framework for building complex multi-entity REST and GraphQL APIs with many relationships in Rust.

Designed for APIs with 5+ entities and complex relationships.
For simple CRUD APIs, consider using Axum directly.

✨ Highlights

🚀 Core Features

🔌 Generic Entity System - Add entities without modifying framework code
🤖 Auto-Generated Routes - Declare a module, routes are created automatically
🏗️ Macro-Driven Entities - Define entities with zero boilerplate using macros
🔒 Type-Safe - Full Rust compile-time guarantees

🔗 Relationship Management

🔗 Flexible Relationships - Multiple link types between same entities
↔️ Bidirectional Navigation - Query relationships from both directions
✨ Auto-Enriched Links - Full entities in responses, no N+1 queries
🎯 Smart Entity Creation - Create new entities + links in one API call

🌐 Multi-Protocol Support

🆕 REST API - Traditional RESTful endpoints with auto-routing
🆕 GraphQL API - Dynamic schema generation with full CRUD and relations
🔜 gRPC (planned) - Extensible architecture for future protocols

⚡ Developer Experience

✅ Automatic Validation & Filtering - Zero-boilerplate data validation with declarative rules
📄 Generic Pagination & Query Filtering - Automatic pagination for all list endpoints
📝 Auto-Pluralization - Smart plural forms (company → companies)
⚙️ YAML Configuration - Declarative entity and link definitions

🎯 Is This-RS Right for You?

✅ Perfect Fit - You Should Use This-RS

Many entities (5+ entities with CRUD operations)
Complex relationships (multiple link types between entities)
Bidirectional navigation (need to query relationships from both directions)
Multi-protocol APIs (want both REST and GraphQL from same codebase)
Microservices architecture (building multiple interconnected services)
Rapid iteration (adding entities frequently, need consistency)

Example use cases: CMS, ERP, e-commerce platforms, social networks, project management tools

⚠️ Probably Overkill - Consider Alternatives

Simple CRUD (< 5 entities with basic operations)
No relationships (entities are independent)
Single small API (not planning to scale)
Learning Rust/Axum (start with Axum directly, add This-RS later if needed)
Maximum performance critical (framework adds small overhead)

For simple projects, use Axum + utoipa directly.

📖 See Alternatives Comparison for detailed analysis of when to use what.

📊 ROI by Project Size

Entities	Relationships	Recommended	Time Saved
1-3	Few	❌ Axum directly	-
3-5	Some	⚠️ Consider This-RS	~20%
5-10	Many	✅ This-RS recommended	~40%
10+	Complex	✅✅ This-RS highly recommended	~60%

💡 What This-RS Actually Saves

Without This-RS (Pure Axum)

// For each entity, you write:
// 1. Entity definition (✓ same in both)
// 2. CRUD handlers (✓ same in both - you still write business logic)
// 3. Routes registration (❌ REPETITIVE - 30+ lines per entity)
// 4. Link routes (❌ REPETITIVE - 50+ lines per relationship)
// 5. Link enrichment (❌ MANUAL - N+1 queries if not careful)
// 6. GraphQL schema (❌ MANUAL - duplicate type definitions)

// Example: 10 entities with 15 relationships
// = ~500 lines of repetitive routing code

With This-RS (✅)

// 1. Entity definition (✓ with macro helpers)
impl_data_entity!(Product, "product", ["name", "sku"], {
    sku: String,
    price: f64,
});

// 2. CRUD handlers (✓ you still write these - it's your business logic)
// 3. Routes registration (✅ AUTO-GENERATED)
// 4. Link routes (✅ AUTO-GENERATED from YAML)
// 5. Link enrichment (✅ AUTOMATIC - no N+1 queries)
// 6. GraphQL schema (✅ AUTO-GENERATED from entities)

// Main.rs for 10 entities with 15 relationships
let app = ServerBuilder::new()
    .register_module(module)?  // ← ~40 lines total
    .build()?;

What you save: Routing boilerplate, link management, GraphQL schema duplication.
What you still write: Business logic handlers (as you should!).

🚀 Quick Example

1. Define Your Entity with Macros

use this::prelude::*;

// Macro generates full entity with all base fields
impl_data_entity!(Product, "product", ["name", "sku"], {
    sku: String,
    price: f64,
    description: Option<String>,
    stock: i32,
});

// Automatically includes:
// - id: Uuid (auto-generated)
// - type: String (auto-set to "product")
// - name: String (required)
// - created_at: DateTime<Utc> (auto-generated)
// - updated_at: DateTime<Utc> (auto-managed)
// - deleted_at: Option<DateTime<Utc>> (soft delete)
// - status: String (required)

2. Create Entity Store with EntityCreator

use this::prelude::*;

#[derive(Clone)]
pub struct ProductStore {
    data: Arc<RwLock<HashMap<Uuid, Product>>>,
}

// Implement EntityFetcher for link enrichment
#[async_trait]
impl EntityFetcher for ProductStore {
    async fn fetch_as_json(&self, entity_id: &Uuid) -> Result<serde_json::Value> {
        let product = self.get(entity_id)
            .ok_or_else(|| anyhow::anyhow!("Product not found"))?;
        Ok(serde_json::to_value(product)?)
    }
}

// Implement EntityCreator for automatic entity creation
#[async_trait]
impl EntityCreator for ProductStore {
    async fn create_from_json(&self, entity_data: serde_json::Value) -> Result<serde_json::Value> {
        let product = Product::new(
            entity_data["name"].as_str().unwrap_or("").to_string(),
            entity_data["status"].as_str().unwrap_or("active").to_string(),
            entity_data["sku"].as_str().unwrap_or("").to_string(),
            entity_data["price"].as_f64().unwrap_or(0.0),
            entity_data["description"].as_str().map(String::from),
            entity_data["stock"].as_i64().unwrap_or(0) as i32,
        );
        self.add(product.clone());
        Ok(serde_json::to_value(product)?)
    }
}

3. Create Module

impl Module for CatalogModule {
    fn name(&self) -> &str { "catalog-service" }
    fn entity_types(&self) -> Vec<&str> { vec!["product"] }
    
    fn links_config(&self) -> Result<LinksConfig> {
        LinksConfig::from_file("config/links.yaml")
    }
    
    fn register_entities(&self, registry: &mut EntityRegistry) {
        registry.register(Box::new(ProductDescriptor::new(self.store.clone())));
    }
    
    fn get_entity_fetcher(&self, entity_type: &str) -> Option<Arc<dyn EntityFetcher>> {
        match entity_type {
            "product" => Some(Arc::new(self.store.clone()) as Arc<dyn EntityFetcher>),
            _ => None,
        }
    }
    
    fn get_entity_creator(&self, entity_type: &str) -> Option<Arc<dyn EntityCreator>> {
        match entity_type {
            "product" => Some(Arc::new(self.store.clone()) as Arc<dyn EntityCreator>),
            _ => None,
        }
    }
}

4. Launch Server (Auto-Generated Routes!)

REST API (Default)

#[tokio::main]
async fn main() -> Result<()> {
    let app = ServerBuilder::new()
        .with_link_service(InMemoryLinkService::new())
        .register_module(CatalogModule::new(store))?
        .build()?;  // ← All REST routes created automatically!
    
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await?;
    axum::serve(listener, app).await?;
    Ok(())
}

GraphQL API (Optional, feature flag)

use this::server::GraphQLExposure;

#[tokio::main]
async fn main() -> Result<()> {
    let host = ServerBuilder::new()
        .with_link_service(InMemoryLinkService::new())
        .register_module(CatalogModule::new(store))?
        .build_host()?;  // ← Build transport-agnostic host
    
    let graphql_app = GraphQLExposure::build_router(Arc::new(host))?;
    
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await?;
    axum::serve(listener, graphql_app).await?;
    Ok(())
}

That's it! Routes are auto-generated:

REST API:

✅ GET /products - List all
✅ POST /products - Create new product
✅ GET /products/:id - Get by ID
✅ PUT /products/:id - Update product
✅ DELETE /products/:id - Delete product
✅ GET /products/:id/links - Introspection
✅ Link routes (if configured in YAML)

GraphQL API:

✅ POST /graphql - GraphQL endpoint with full CRUD
✅ GET /graphql/playground - Interactive GraphQL playground
✅ GET /graphql/schema - Dynamic schema introspection
✅ Auto-generated types (Product, Order, etc.)
✅ Auto-generated queries (products, product(id))
✅ Auto-generated mutations (createProduct, updateProduct, deleteProduct)
✅ Auto-resolved relations (follow links automatically)

🔗 Advanced Link Features

Two Ways to Create Links

1. Link Existing Entities

# POST /orders/{order_id}/invoices/{invoice_id}
curl -X POST http://localhost:3000/orders/abc-123/invoices/inv-456 \
  -H 'Content-Type: application/json' \
  -d '{"metadata": {"priority": "high"}}'

2. Create New Entity + Link Automatically

# POST /orders/{order_id}/invoices
curl -X POST http://localhost:3000/orders/abc-123/invoices \
  -H 'Content-Type: application/json' \
  -d '{
    "entity": {
      "number": "INV-999",
      "amount": 1500.00,
      "status": "active"
    },
    "metadata": {"priority": "high"}
  }'

# Response includes both created entity AND link!
{
  "entity": {
    "id": "inv-999-uuid",
    "type": "invoice",
    "name": "INV-999",
    "amount": 1500.00,
    ...
  },
  "link": {
    "id": "link-uuid",
    "source_id": "abc-123",
    "target_id": "inv-999-uuid",
    ...
  }
}

Auto-Enriched Link Responses

When you query links, you automatically get full entity data:

# GET /orders/{id}/invoices
{
  "links": [
    {
      "id": "link-123",
      "source_id": "order-abc",
      "target_id": "invoice-xyz",
      "target": {
        "id": "invoice-xyz",
        "type": "invoice",
        "name": "INV-001",
        "amount": 1500.00,
        ...
      }
    }
  ]
}

No N+1 queries! Entities are fetched efficiently in the background.

📚 Examples

Microservice Example

Complete billing microservice with auto-generated routes for both REST and GraphQL:

REST API

cargo run --example microservice

Output:

🚀 Starting billing-service v1.0.0
📦 Entities: ["order", "invoice", "payment"]
🌐 Server running on http://127.0.0.1:3000

📚 Entity Routes (CRUD - Auto-generated):
  GET    /orders                        - List all orders
  POST   /orders                        - Create a new order
  GET    /orders/{id}                   - Get a specific order
  PUT    /orders/{id}                   - Update an order
  DELETE /orders/{id}                   - Delete an order

🔗 Link Routes (Auto-generated):
  GET    /orders/{id}/invoices          - List invoices for an order
  POST   /orders/{id}/invoices          - Create new invoice + link automatically
  POST   /orders/{id}/invoices/{inv_id} - Link existing order & invoice
  PUT    /orders/{id}/invoices/{inv_id} - Update link metadata
  DELETE /orders/{id}/invoices/{inv_id} - Delete link

See examples/microservice/README.md for full REST API details.

GraphQL API

cargo run --example microservice_graphql --features graphql

The same entities are exposed via GraphQL with:

Dynamic Schema Generation - Types (Order, Invoice, Payment) auto-generated
Full CRUD - Queries and mutations for all entities
Automatic Relations - Navigate order.invoices, invoice.payments automatically
Interactive Playground - Test queries at http://127.0.0.1:3000/graphql/playground

Example query:

query {
  orders {
    id
    number
    customerName
    amount
    invoices {
      id
      number
      amount
      payments {
        id
        amount
        method
      }
    }
  }
}

See examples/microservice/README_GRAPHQL.md for full GraphQL details.

🏗️ Architecture

Entity Hierarchy

Entity (Base Trait)
├── id: Uuid
├── type: String
├── created_at: DateTime<Utc>
├── updated_at: DateTime<Utc>
├── deleted_at: Option<DateTime<Utc>>
└── status: String

    ├─► Data (Inherits Entity)
    │   └── name: String
    │       + indexed_fields()
    │       + field_value()
    │
    └─► Link (Inherits Entity)
        ├── source_id: Uuid
        ├── target_id: Uuid
        └── link_type: String

Core Concepts

ServerBuilder - Fluent API for building HTTP servers
EntityDescriptor - Describes how to generate routes for an entity
EntityRegistry - Collects and builds all entity routes
Module - Groups related entities with configuration
LinkService - Generic relationship management
EntityFetcher - Dynamically fetch entities for link enrichment
EntityCreator - Dynamically create entities with automatic linking

Macro System

impl_data_entity! - Generate a complete Data entity
impl_link_entity! - Generate a custom Link entity
entity_fields! - Inject base Entity fields
data_fields! - Inject Entity + name fields
link_fields! - Inject Entity + link fields

📖 Documentation

🚀 Getting Started

Quick Start - Fast introduction
Getting Started - Step-by-step tutorial

🌐 API Exposure

GraphQL Guide - 🆕 Dynamic GraphQL API with auto-generated schema
Custom Routes - Adding custom endpoints alongside auto-routes

🔗 Features

Validation & Filtering - Automatic data validation
Pagination & Filtering - Generic pagination and query filtering
Enriched Links - Auto-enrichment & performance
Link Authorization - Securing relationships

🏗️ Architecture

Architecture - Technical deep dive
ServerBuilder - Auto-routing details
GraphQL Implementation - 🆕 Custom executor design
Full Documentation - Complete documentation index

🎁 Key Benefits

For Developers

✅ -88% less routing boilerplate (340 → 40 lines in microservice example)
✅ Add entity quickly - Macro helpers + module registration
✅ Consistent patterns - Same structure for all entities
✅ Type-safe - Full Rust compile-time checks
✅ Scales well - Adding the 10th entity is as easy as the 1st
✅ Multi-protocol - 🆕 Same entities exposed via REST and GraphQL
⚠️ Learning curve - Framework abstractions to understand (traits, registry)

For Teams

✅ Faster development - Less code to write and maintain
✅ Easier onboarding - Clear patterns and conventions
✅ Reduced errors - Less manual work = fewer mistakes
✅ Better consistency - Framework enforces best practices
✅ Flexible APIs - 🆕 Choose REST, GraphQL, or both

For Production

✅ Authorization - Declarative auth policies
✅ Configurable - YAML-based configuration
✅ Extensible - Plugin architecture via modules
✅ Performance - Efficient link enrichment with no N+1 queries
✅ Soft Deletes - Built-in soft delete support
✅ Dynamic Schema - 🆕 GraphQL schema auto-generated from entities

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE-MIT file for details.

🌟 Why This-RS?

"The best code is the code you don't have to write... if you're writing it 50 times."

This-RS eliminates repetitive routing and relationship boilerplate while maintaining type safety.

Perfect for:

🏢 Microservices architectures with many entities
🔗 Complex relationship graphs (many-to-many, bidirectional)
🔮 Dynamic GraphQL + REST from same definitions
🚀 Rapidly evolving domains (adding entities frequently)
📊 Data-rich applications with interconnected entities

NOT ideal for:

❌ Simple CRUD APIs (< 5 entities)
❌ Maximum performance critical paths (framework adds overhead)
❌ Learning projects (start with Axum first)

🆕 What's New in v0.0.6

✨ GraphQL Support - Auto-generated GraphQL schema from your entities
🔄 Dynamic Schema - Types, queries, and mutations created at runtime
🔗 Automatic Relations - Navigate entity relationships in GraphQL
🎯 Full CRUD - Complete create, read, update, delete via GraphQL
🏗️ Modular Architecture - Choose REST, GraphQL, or both

🤔 Honest Trade-offs

What This-RS Adds ✅

Auto-generated routing for entities and links
Bidirectional relationship navigation
Link enrichment (no N+1 queries)
GraphQL schema from REST entities
YAML-based relationship configuration

What You Still Write ✍️

Entity definitions (with macro helpers)
Business logic handlers (create, update, delete, custom queries)
Validation rules
Authorization logic
Error handling

The Cost ⚠️

Learning curve (framework patterns and traits)
Some abstraction overhead (dynamic dispatch, registry lookups)
YAML configuration to maintain
Smaller ecosystem than pure Axum

Built with Rust. Designed for complex APIs. Best for scale. 🦀✨

this-rs 0.0.6

This-RS 🦀

✨ Highlights

🚀 Core Features

🔗 Relationship Management

🌐 Multi-Protocol Support

⚡ Developer Experience

🎯 Is This-RS Right for You?

✅ Perfect Fit - You Should Use This-RS

⚠️ Probably Overkill - Consider Alternatives

📊 ROI by Project Size

💡 What This-RS Actually Saves

Without This-RS (Pure Axum)

With This-RS (✅)

🚀 Quick Example

1. Define Your Entity with Macros

2. Create Entity Store with EntityCreator

3. Create Module

4. Launch Server (Auto-Generated Routes!)

REST API (Default)

GraphQL API (Optional, feature flag)

🔗 Advanced Link Features

Two Ways to Create Links

1. Link Existing Entities

2. Create New Entity + Link Automatically

Auto-Enriched Link Responses

📚 Examples

Microservice Example

REST API

GraphQL API

🏗️ Architecture

Entity Hierarchy

Core Concepts

Macro System

📖 Documentation

🚀 Getting Started

🌐 API Exposure

🔗 Features

🏗️ Architecture

🎁 Key Benefits

For Developers

For Teams

For Production

🤝 Contributing

📄 License

🌟 Why This-RS?

🆕 What's New in v0.0.6

🤔 Honest Trade-offs

What This-RS Adds ✅

What You Still Write ✍️

The Cost ⚠️