Crate apithing 

ApiThing

A standardized API approach based on content and parameter traits.

This crate provides a framework for building APIs using a trait-based approach where operations are defined using shared contexts and parameter objects. The framework enables consistent patterns across different API families while allowing for flexible context sharing and type-safe operation execution.

Quick Start

use apithing::{ApiOperation, ApiExecutor};

// Define your operation parameters
#[derive(Debug, Clone)]
struct CreateEntityParameters {
    name: String,
    data: String,
}

// Define your data types
#[derive(Debug, Clone)]
struct Entity {
    id: u64,
    name: String,
    data: String,
}

// Define your errors
#[derive(Debug)]
enum EntityError {
    ValidationFailed,
}

// Implement your operation
struct CreateEntity;
// Define a custom context for your application
#[derive(Debug)]
struct MyAppContext {
    connection: String,
    counter: u64,
}

impl MyAppContext {
    fn new(connection: String) -> Self {
        Self { connection, counter: 0 }
    }
    fn next_id(&mut self) -> u64 {
        self.counter += 1;
        self.counter
    }
}

impl ApiOperation<MyAppContext, CreateEntityParameters> for CreateEntity {
    type Output = Entity;
    type Error = EntityError;

    fn execute(context: &mut MyAppContext, parameters: &CreateEntityParameters) -> Result<Entity, EntityError> {
        if parameters.name.is_empty() {
            return Err(EntityError::ValidationFailed);
        }

        let entity = Entity {
            id: context.next_id(),
            name: parameters.name.clone(),
            data: parameters.data.clone(),
        };
        Ok(entity)
    }
}

// Usage
let mut context = MyAppContext::new("db".to_string());
let parameters = CreateEntityParameters {
    name: "Example".to_string(),
    data: "example@data.com".to_string(),
};
let entity = CreateEntity::execute(&mut context, &parameters).unwrap();

Core Architecture

The ApiThing framework is built around several key concepts:

graph TB
    Context["Context (C)<br/>• Shared state<br/>• Resources<br/>• Connections"]
    Operation["ApiOperation&lt;C,P&gt;<br/>fn execute()<br/>→ Output<br/>→ Error"]
    Parameters["Parameters (P)<br/>• Input params<br/>• Validation<br/>• Type safety"]

    Execute["Execute&lt;C,P&gt;<br/>execute_on()<br/>(ergonomic API)"]
    Props["Operation Parameters<br/>Entity Props<br/>Domain Props<br/>..."]

    ApiExecutor["ApiExecutor&lt;C&gt;<br/>• Stateful<br/>• Context mgmt<br/>• Multi-ops"]

    Context --> Operation
    Parameters --> Operation
    Operation --> Execute
    Parameters --> Props
    Execute --> ApiExecutor

Multi-Family API Design

ApiThing supports multiple API families sharing common infrastructure:

                   Shared DatabaseContext
                  ┌─────────────────────┐
                  │ • Connection Pool   │
                  │ • Cache            │
                  │ • Transaction Log  │
                  │ • Metrics          │
                  └─────────────────────┘
                           │
             ┌──────────────┼──────────────┐
             │              │              │
        Domain API      Entity API    Service API
   ┌─────────────────┐ ┌─────────────┐ ┌─────────────┐
   │ • Create        │ │ • Create    │ │ • Execute   │
   │ • Find          │ │ • Find      │ │ • Process   │
   │ • Update        │ │ • Update    │ │ • Transform │
   └─────────────────┘ └─────────────┘ └─────────────┘

This design enables:

• Context sharing: Operations across families share resources efficiently
• Type safety: Each family has its own types but shares infrastructure
• Composability: Operations can call operations from other families
• Consistency: All families follow the same patterns and conventions

Structs

ApiExecutor

A stateful executor for API operations that maintains context across multiple calls.

Traits

ApiOperation

Core trait that all API operations implement.

Execute

A trait providing ergonomic method-style execution for API operations.