reinhardt-rest 0.1.0-alpha.19

REST API framework aggregator for Reinhardt
Documentation

reinhardt-rest

Export-only integration layer for Reinhardt REST API framework.

Overview

This crate serves as a convenience layer that combines multiple Reinhardt crates into a single import. It does not contain its own implementation or tests - all functionality is provided by the underlying specialized crates.

Installation

Add reinhardt to your Cargo.toml:

[dependencies]
reinhardt = { version = "0.1.0-alpha.1", features = ["rest"] }

# Or use a preset:
# reinhardt = { version = "0.1.0-alpha.1", features = ["standard"] }  # Recommended
# reinhardt = { version = "0.1.0-alpha.1", features = ["full"] }      # All features

Then import REST features:

use reinhardt::rest::{ApiResponse, ResponseBuilder, IntoApiResponse};
use reinhardt::rest::{JwtAuth, IsAuthenticated, AllowAny, User, SimpleUser};
use reinhardt::rest::{DefaultRouter, Router, Route};
use reinhardt::rest::{PaginatedResponse};

Note: REST features are included in the standard and full feature presets.

Purpose

  • Unified Interface: Single import point for REST API functionality
  • Re-export Layer: Combines authentication, routing, browsable API, and response handling
  • No Implementation: Pure export/aggregation crate
  • No Tests: All functionality is tested in specialized crates

Features

Implemented ✓

Authentication (from reinhardt-auth)

  • JWT Authentication: Stateless authentication using JSON Web Tokens
    • JwtAuth - JWT authentication backend
    • Claims - JWT claims structure
  • User Types:
    • User - Base user trait
    • SimpleUser - Simple user implementation
    • AnonymousUser - Unauthenticated user representation
  • Permission Classes:
    • AllowAny - Allow all users (authenticated or not)
    • IsAuthenticated - Require authentication
    • IsAuthenticatedOrReadOnly - Read-only for anonymous, full access for authenticated
    • IsAdminUser - Require admin privileges
  • REST-specific Utilities:
    • AuthResult<U> - Result type for authentication operations
    • AuthBackend - Authentication backend trait

Routing (from reinhardt-routers)

  • Router Types:
    • DefaultRouter - Default router with automatic ViewSet URL generation
    • Router - Base router trait
  • URL Patterns:
    • Route - Individual route definition
    • UrlPattern - URL pattern matching

Browsable API (from reinhardt-browsable-api)

  • HTML Interface: Interactive API explorer for development and testing
  • Automatic Documentation: Self-documenting API endpoints

Response Handling

  • Response Types:
    • ApiResponse<T> - DRF-style API response wrapper
      • Success responses (success, success_with_status)
      • Error responses (error, validation_error)
      • Standard HTTP responses (not_found, unauthorized, forbidden)
    • ResponseBuilder<T> - Fluent builder for API responses
  • Utilities:
    • IntoApiResponse<T> - Trait for converting types to API responses
    • PaginatedResponse - Paginated response wrapper (from reinhardt-pagination)

Schema Generation (from reinhardt-openapi)

  • OpenAPI/Swagger:
    • OpenApiSchema - OpenAPI 3.0 schema generation
    • Components - Reusable schema components
    • Operation - API operation definitions
    • Parameter - Request parameter definitions
    • Server - Server configuration
    • Auto-schema generation from Rust types
    • SwaggerUI - Interactive API documentation

Pagination (from reinhardt-pagination)

  • Pagination Strategies:
    • PageNumberPagination - Page-based pagination
    • LimitOffsetPagination - Offset-based pagination
    • CursorPagination - Cursor-based pagination

Filtering (from reinhardt-filters)

  • Filter Backends:
    • SearchFilter - Search across multiple fields
    • OrderingFilter - Sort results by fields
    • QueryFilter - Type-safe query filtering
    • MultiTermSearch - Multi-term search operations

Throttling/Rate Limiting (from reinhardt-throttling)

  • Throttling Classes:
    • AnonRateThrottle - Rate limiting for anonymous users
    • UserRateThrottle - Rate limiting for authenticated users
    • ScopedRateThrottle - Per-endpoint rate limiting

Signals/Hooks (from reinhardt-signals)

  • Model Signals:
    • pre_save, post_save - Model save signals
    • pre_delete, post_delete - Model delete signals
    • m2m_changed - Many-to-many relationship signals

Testing

This crate does not contain tests. All functionality is tested in the underlying specialized crates:

  • Authentication tests: reinhardt-auth/tests/
  • Router tests: reinhardt-routers/tests/
  • Browsable API tests: reinhardt-browsable-api/tests/
  • Response handling tests: Documentation tests in src/response.rs
  • Integration tests: tests/integration/

Usage

use reinhardt::rest::{
    // Authentication
    JwtAuth, IsAuthenticated, AllowAny, User, SimpleUser,

    // Routing
    DefaultRouter, Router, Route,

    // Response handling
    ApiResponse, ResponseBuilder, IntoApiResponse,

    // Pagination
    PaginatedResponse,
};

// Create a successful response
let user = SimpleUser::new(1, "Alice");
let response = ApiResponse::success(user);

// Build a custom response
let response = ResponseBuilder::new()
    .data("Success")
    .status(201)
    .message("Resource created")
    .build();

// Convert Result to ApiResponse
let result: Result<String, String> = Ok("data".to_string());
let response = result.into_api_response();

browsable-api

Features

Implemented ✓

Core Rendering

  • BrowsableApiRenderer: Handlebars-based HTML template renderer
    • Default DRF-inspired template with gradient header design
    • Customizable template registration support
    • JSON response pretty-printing and syntax highlighting
    • Responsive design with modern CSS styling
  • ApiContext: Complete context structure for API rendering
    • Title, description, endpoint, and HTTP method display
    • Response data with status code
    • Allowed HTTP methods visualization
    • Request headers display in table format
    • Optional form context integration

Response Handling

  • BrowsableResponse: Structured API response type
    • Data payload with serde_json::Value support
    • ResponseMetadata with status, method, path, and headers
    • Convenience constructors (new, success)
    • Full serialization/deserialization support

Form Generation

  • FormContext: Interactive request form rendering
    • Dynamic form field generation
    • Support for multiple input types (text, textarea, etc.)
    • Required field indicators
    • Help text for field guidance
    • Initial value support for form fields
  • FormField: Individual form field configuration
    • Field name, label, and type specification
    • Required/optional field handling
    • Help text and initial value support

Template System

  • ApiTemplate: Basic HTML template utilities
    • Simple API response rendering
    • Error page generation with status codes
    • Fallback templates for simple use cases

Visual Features

  • HTTP method badges with color coding (GET, POST, PUT, PATCH, DELETE)
  • Monospace endpoint display
  • Dark theme code blocks for JSON responses
  • Responsive container layout with shadow effects
  • Form styling with proper input controls
  • Header table display with clean formatting

openapi

Features

Implemented ✓

OpenAPI 3.0 Core Types

  • Complete OpenAPI 3.0 Specification: Full support for OpenAPI 3.0 types via utoipa re-exports
    • Info, Contact, License metadata
    • Paths, PathItem, Operation definitions
    • Parameter definitions (Query, Header, Path, Cookie locations)
    • Request/Response body schemas
    • Components and reusable schemas
    • Security schemes (HTTP, ApiKey, OAuth2)
    • Server definitions with variables
    • Tag definitions for API organization

Schema Generation

  • SchemaGenerator: Builder pattern for creating OpenAPI schemas
    • Fluent API for setting title, version, description
    • Direct generation to OpenApiSchema (utoipa's OpenApi type)

Documentation UI

  • Swagger UI Integration: Built-in Swagger UI via utoipa-swagger-ui
    • HTML rendering with customizable title and spec URL
    • Request handler for serving Swagger UI pages
    • Automatic OpenAPI spec serving at /api/openapi.json
    • Schema JSON export functionality
  • Redoc UI Support: Alternative documentation interface
    • HTML rendering for Redoc
    • Request handler for serving Redoc pages
    • Uses same OpenAPI spec endpoint

Format Export

  • JSON Export: Serialize OpenAPI schemas to JSON format
  • YAML Export: Support via serde_yaml dependency (capability present in dependencies)

utoipa Compatibility Layer

  • Bidirectional Type Conversion: Complete conversion utilities between Reinhardt and utoipa types
    • Schema type conversions (Object, Array, primitives)
    • Parameter and request/response body conversions
    • Security scheme conversions (HTTP, ApiKey, OAuth2)
    • Server and tag conversions
    • Format and schema type mappings
    • Comprehensive test coverage

Auto-Schema Derivation

  • ToSchema Trait: Core trait for types that can generate OpenAPI schemas

    • schema() method returns OpenAPI schema representation
    • schema_name() method returns optional schema identifier
    • Implemented for all Rust primitive types (i8-i64, u8-u64, f32-f64, bool, String)
    • Generic implementations for Option<T> and Vec<T>

  • Schema Derive Macro: #[derive(Schema)] procedural macro for automatic schema generation

    • Automatic field metadata extraction (type, required, nullable)
    • Support for struct types with named fields
    • Automatic required field detection (Option<T> fields are optional)
    • Doc comment extraction for field descriptions
    • Support for enum types with string variant generation
    • Compatible with utoipa 5.4 ObjectBuilder pattern

Extended Auto-Schema Features

  • Attribute Macro Support: Advanced schema customization
    • Field configuration: #[schema(example = "...", description = "...")]
    • Nested schema generation with $ref references
    • Advanced enum handling (tagged, adjacently tagged, untagged)
    • Integration with serde attributes (#[serde(rename)], #[serde(skip)])
    • Schema registry for component reuse
    • Validation constraint reflection (min, max, pattern)
    • Example value generation
  • HashMap Support: HashMap<K,V> schema generation
  • Tuple Struct Support: Schema generation for tuple structs

ViewSet Integration

  • ViewSet Inspector: Automatic schema extraction from ViewSets
    • Introspect ViewSet methods and serializers
    • Generate paths and operations from ViewSet definitions
    • Extract parameter information from method signatures
    • Automatic request/response schema generation from serializers

serializers

Features

Implemented ✓

Core Serialization

  • Serializer trait: Generic trait for data serialization and deserialization

    • serialize(): Convert Rust types to output format
    • deserialize(): Parse output format back to Rust types
    • SerializerError: Type-safe error handling for serialization failures

  • JsonSerializer<T>: JSON serialization implementation

    • Built on serde_json for efficient JSON handling
    • Supports any type implementing Serialize and Deserialize
    • Automatic conversion between Rust types and JSON strings

  • Deserializer trait: Dedicated deserialization interface

    • Separate trait for read-only deserialization operations
    • Enables more flexible data parsing pipelines

Model Serialization

  • ModelSerializer<M>: Automatic serialization for ORM models
    • Django-style automatic field mapping from model definitions
    • Built-in validation support with validate() method
    • Seamless integration with reinhardt-orm::Model trait
    • JSON serialization/deserialization for database models
    • Extensible validation system for custom business logic
    • Meta Configuration: Field inclusion/exclusion, read-only/write-only fields
    • Field Introspection: Automatic detection of model fields and types
    • Nested Serializer Support: Configure and serialize related objects
    • Validator Integration: Built-in database constraint validation

Meta Configuration

  • MetaConfig: Django REST Framework-style Meta options
    • fields: Explicitly include specific fields
    • exclude: Exclude specific fields
    • read_only_fields: Mark fields as read-only
    • write_only_fields: Mark fields as write-only (e.g., passwords)
    • Builder pattern with chainable methods
    • Comprehensive doctests (4 tests) and unit tests (8 tests)

Field Introspection

  • FieldIntrospector: Automatic field discovery and type inference

    • Register fields with FieldInfo (name, type, optional, collection, primary key)
    • Query fields: field_names(), required_fields(), optional_fields(), primary_key_field()
    • Type mapping with TypeMapper for common Rust types
    • Integration with ModelSerializer for automatic field detection
    • Comprehensive unit tests (14 tests) and integration tests (10 tests)

  • FieldInfo: Rich field metadata

    • Field name, type name, optionality, collection status
    • Primary key identification
    • Builder pattern for configuration

Nested Serialization

  • NestedSerializerConfig: Configure nested object serialization

    • Per-field depth control
    • Read-only vs writable nested fields
    • Create/update permissions (allow_create, allow_update)
    • Flexible nested field configuration
    • Comprehensive unit tests (11 tests)

  • NestedFieldConfig: Individual nested field configuration

    • depth(): Set nesting depth (default: 1)
    • read_only(): Mark as read-only
    • writable(): Enable create/update operations
    • allow_create(), allow_update(): Fine-grained permissions

  • SerializationContext: Circular reference and depth management

    • Track visited objects to prevent infinite loops
    • Max depth enforcement
    • Context-aware traversal methods
    • Comprehensive unit tests (15 tests) and integration tests (17 tests)

  • RecursiveError: Error handling for nested serialization

    • MaxDepthExceeded: Nesting too deep
    • CircularReference: Circular dependency detected
    • SerializationError: Generic serialization failures

Validator Configuration

  • ValidatorConfig<M>: Manage validators for ModelSerializer
    • Register UniqueValidator and UniqueTogetherValidator
    • Query registered validators
    • Type-safe validator management
    • Comprehensive unit tests (4 tests) and integration tests (17 tests)

Database Validators

  • UniqueValidator<M>: Enforce field uniqueness in database

    • Async validation against PostgreSQL database
    • Supports update operations (excludes current instance from uniqueness check)
    • Customizable field names and error messages
    • Database-level uniqueness verification
    • Builder pattern with with_message() for custom error messages
    • Cloneable and debuggable
    • Comprehensive unit tests (4 tests)

  • UniqueTogetherValidator<M>: Ensure unique field combinations

    • Multi-field uniqueness constraints
    • Async PostgreSQL validation
    • Support for update operations
    • Customizable error messages with with_message()
    • Flexible field combinations
    • Cloneable and debuggable
    • Comprehensive unit tests (4 tests)

Error Handling

  • SerializerError: Comprehensive error type for all serialization operations

    • Validation(ValidatorError): Validation errors with detailed context
    • Serde { message }: Serialization/deserialization errors
    • Other { message }: Generic errors
    • Helper constructors: unique_violation(), unique_together_violation(), required_field(), database_error()
    • is_validation_error(), as_validator_error() for error inspection
    • Comprehensive error handling tests (22 tests)

  • ValidatorError: Detailed validation error information

    • UniqueViolation: Single field uniqueness violation
    • UniqueTogetherViolation: Multi-field uniqueness violation
    • RequiredField: Missing required field
    • FieldValidation: Field constraint violation (regex, range, etc.)
    • DatabaseError: Database operation errors
    • Custom: Generic validation errors
    • Rich error context with field names, values, and constraints
    • Methods: message(), field_names(), is_database_error(), is_uniqueness_violation()

Content Negotiation (Re-exported)

  • ContentNegotiator: Select appropriate response format based on client request
  • MediaType: Parse and compare media type strings

Parsers (Re-exported from reinhardt-parsers)

  • JSONParser: Parse JSON request bodies
  • FormParser: Parse form-encoded data
  • MultiPartParser: Handle multipart/form-data (file uploads)
  • FileUploadParser: Direct file upload handling
  • ParseError: Error type for parsing failures

Field Types

  • FieldError: Comprehensive error types for field validation failures
    • 14 error variants covering all validation scenarios
    • Display implementation for user-friendly error messages
  • CharField: String field with length validation
    • Builder pattern with min_length(), max_length(), required(), allow_blank()
    • Default value support
    • Comprehensive doctests (7 tests) and unit tests (3 tests)
  • IntegerField: Integer field with range validation
    • Builder pattern with min_value(), max_value(), required(), allow_null()
    • i64 value support
    • Comprehensive doctests (6 tests) and unit tests (3 tests)
  • FloatField: Floating-point field with range validation
    • Builder pattern with min_value(), max_value(), required(), allow_null()
    • f64 value support
    • Comprehensive doctests (6 tests) and unit tests (1 test)
  • BooleanField: Boolean field handling
    • Builder pattern with required(), allow_null(), default()
    • Always valid validation (booleans can't be invalid)
    • Comprehensive doctests (3 tests) and unit tests (1 test)
  • EmailField: Email format validation
    • Builder pattern with required(), allow_blank(), allow_null()
    • Basic RFC-compliant email validation (@ sign, domain with dot)
    • Comprehensive doctests (4 tests) and unit tests (2 tests)
  • URLField: URL format validation
    • Builder pattern with required(), allow_blank(), allow_null()
    • HTTP/HTTPS protocol validation
    • Comprehensive doctests (4 tests) and unit tests (2 tests)
  • ChoiceField: Enumerated value validation
    • Builder pattern with required(), allow_blank(), allow_null()
    • Configurable list of valid choices
    • Comprehensive doctests (3 tests) and unit tests (2 tests)

Advanced Serialization

  • SerializerMethodField: Compute custom read-only fields

    • Method-based computed fields for serializers
    • Custom method names with .method_name()
    • HashMap-based context for method values
    • Read-only field support (always read_only: true)
    • Example: full_name field computed from first_name + last_name
    • Comprehensive doctests (2 tests) and unit tests (7 tests)

  • MethodFieldProvider trait: Support for serializers with method fields

    • compute_method_fields(): Generate all method field values
    • compute_method(): Generate single method field value
    • Integration with serializer context

  • MethodFieldRegistry: Manage multiple method fields

    • Register method fields with .register()
    • Retrieve fields with .get() and .contains()
    • Access all fields with .all()

Validation System

  • ValidationError: Structured validation error messages

    • FieldError: Single field validation errors with field name and message
    • MultipleErrors: Collection of multiple validation errors
    • ObjectError: Object-level validation errors
    • Helper methods: field_error(), object_error(), multiple()
    • thiserror integration for error handling

  • FieldValidator trait: Field-level validation

    • validate(): Validate individual field values
    • Implemented by custom validators (EmailValidator, AgeValidator, etc.)
    • JSON Value-based validation

  • ObjectValidator trait: Object-level validation

    • validate(): Validate entire objects with multiple fields
    • Cross-field validation support
    • Example: Password confirmation matching

  • FieldLevelValidation trait: Serializer field-level validation

    • validate_field(): Validate specific field by name
    • get_field_validators(): Get all registered field validators
    • Django-style validate_<field>() pattern support

  • ObjectLevelValidation trait: Serializer object-level validation

    • validate(): Validate entire serialized object
    • Called after all field validations pass

  • validate_fields() helper: Validate all fields in a data object

    • Takes HashMap of field validators
    • Returns single error or MultipleErrors
    • Comprehensive doctests (3 tests) and unit tests (13 tests)

Advanced Relations

Hyperlinked Model Serializer

  • HyperlinkedModelSerializer: Django REST Framework-style hyperlinked serialization
  • UrlReverser Trait: Automatic URL generation for resources
  • View Name Mapping: Generate URLs based on view names
  • Custom URL Fields: Configurable URL field names
use reinhardt::rest::serializers::HyperlinkedModelSerializer;

let serializer = HyperlinkedModelSerializer::<User>::new("user-detail", None);
// Generates URLs like: {"url": "/api/users/123/", "username": "alice"}

// When using UrlReverser
// let reverser: Arc<dyn UrlReverser> = Arc::new(MyUrlReverser);
// let serializer = HyperlinkedModelSerializer::<User>::new("user-detail", Some(reverser));

Nested Serializers

  • NestedSerializer<M, R>: Handle nested object serialization
  • Relationship Fields: Serialize related models inline
  • Depth Control: Configure nesting depth
  • Bidirectional Relations: Support for parent-child relationships
use reinhardt::rest::serializers::NestedSerializer;

let serializer = NestedSerializer::<Post, User>::new("author", 2);
// Serializes: {"title": "Post", "author": {"id": 1, "username": "alice"}}

Relation Fields

  • PrimaryKeyRelatedField: Represent relations using primary keys
  • SlugRelatedField: Represent relations using slug fields
  • StringRelatedField: Read-only string representation of related objects
  • Flexible Representation: Choose the best representation for your API
use reinhardt::rest::serializers::{PrimaryKeyRelatedField, SlugRelatedField};

// Primary key relation: {"author": 123}
let pk_field = PrimaryKeyRelatedField::<User>::new();

// Slug relation: {"author": "alice-smith"}
let slug_field = SlugRelatedField::<User>::new("slug");

ORM Integration

QuerySet Integration

  • SerializerSaveMixin trait: Django-style save interface for serializers
  • SaveContext: Transaction-aware context for save operations
  • Manager Integration: Automatic ORM create/update operations
use reinhardt::rest::serializers::{SerializerSaveMixin, SaveContext};
use reinhardt::db::orm::{Model, Manager};

// Create new instance
let context = SaveContext::new();
let user = serializer.save(context).await?;

// Update existing instance
let context = SaveContext::with_instance(existing_user);
let updated_user = serializer.update(validated_data, existing_user).await?;

Transaction Management

  • TransactionHelper: RAII-based transaction management
  • Automatic Rollback: Drop-based cleanup on errors
  • Savepoint Support: Nested transaction handling
use reinhardt::rest::serializers::TransactionHelper;

// Wrap operations in transaction
TransactionHelper::with_transaction(|| async {
    // All database operations here are atomic
    let user = manager.create(user_data).await?;
    let profile = manager.create(profile_data).await?;
    Ok((user, profile))
}).await?;

// Nested transactions with savepoints
TransactionHelper::savepoint(depth, || async {
    // Nested operation with automatic savepoint
    manager.update(instance).await
}).await?;

Nested Save Context

  • NestedSaveContext: Depth-aware transaction management
  • Automatic Scope Selection: Transaction vs savepoint based on depth
  • Hierarchical Operations: Support for deeply nested serializers
use reinhardt::rest::serializers::NestedSaveContext;

let context = NestedSaveContext::new(depth);

// Automatically uses transaction (depth=0) or savepoint (depth>0)
context.with_scope(|| async {
    // Nested serializer save operations
    nested_serializer.save(data).await
}).await?;

Many-to-Many Relationship Management

  • ManyToManyManager: Junction table operations
  • Bulk Operations: Efficient batch insert/delete
  • Set Operations: Replace all relationships atomically
use reinhardt::rest::serializers::ManyToManyManager;

let m2m_manager = ManyToManyManager::<User, Tag>::new(
    "user_tags",      // Junction table
    "user_id",        // Source FK
    "tag_id"          // Target FK
);

// Add multiple relationships
m2m_manager.add_bulk(&user_id, vec![tag1_id, tag2_id, tag3_id]).await?;

// Remove specific relationships
m2m_manager.remove_bulk(&user_id, vec![tag1_id]).await?;

// Replace all relationships atomically
m2m_manager.set(&user_id, vec![tag4_id, tag5_id]).await?;

// Clear all relationships
m2m_manager.clear(&user_id).await?;

Relation Field Database Lookups

  • PrimaryKeyRelatedFieldORM: Database-backed primary key relations
  • SlugRelatedFieldORM: Database-backed slug field relations
  • Batch Query Optimization: IN clause for multiple lookups
  • Custom QuerySet Filters: Additional filtering constraints
use reinhardt::rest::serializers::{PrimaryKeyRelatedFieldORM, SlugRelatedFieldORM};
use reinhardt::db::orm::{Filter, FilterOperator, FilterValue};

// Primary key relation with database validation
let pk_field = PrimaryKeyRelatedFieldORM::<User>::new();

// Validate existence in database
pk_field.validate_exists(&user_id).await?;

// Fetch single instance
let user = pk_field.get_instance(&user_id).await?;

// Batch fetch (prevents N+1 queries)
let users = pk_field.get_instances(vec![id1, id2, id3]).await?;

// Slug field relation with custom filter
let slug_field = SlugRelatedFieldORM::<User>::new("username")
    .with_queryset_filter(Filter::new(
        "is_active",
        FilterOperator::Eq,
        FilterValue::Bool(true)
    ));

// Validate slug exists
slug_field.validate_exists(&slug_value).await?;

// Fetch by slug
let user = slug_field.get_instance(&slug_value).await?;

// Batch fetch by slugs
let users = slug_field.get_instances(vec!["alice", "bob", "charlie"]).await?;

Performance Optimization

  • IntrospectionCache: Cache field metadata to avoid repeated introspection
  • QueryCache: TTL-based query result caching
  • BatchValidator: Combine multiple database checks into single queries
  • PerformanceMetrics: Track serialization and validation performance
use reinhardt::rest::serializers::{IntrospectionCache, QueryCache, BatchValidator, PerformanceMetrics};
use std::time::Duration;

// Cache field introspection results
let cache = IntrospectionCache::new();
if let Some(fields) = cache.get("User") {
    // Use cached fields
} else {
    let fields = introspect_fields();
    cache.set("User".to_string(), fields);
}

// Query result caching with TTL
let query_cache = QueryCache::new(Duration::from_secs(300));
query_cache.set("user:123".to_string(), user_data);

// Batch validation
let mut validator = BatchValidator::new();
validator.add_unique_check("users", "email", "alice@example.com");
validator.add_unique_check("users", "username", "alice");
let failures = validator.execute().await?;

// Performance tracking
let metrics = PerformanceMetrics::new();
metrics.record_serialization(50); // 50ms
let stats = metrics.get_stats();
println!("Average: {}ms", stats.avg_serialization_ms);

Note: ORM integration features (Django-like QuerySet API and SQLAlchemy-like query builder) are available by default. Both patterns can be used interchangeably for database operations.

Additional Field Types

  • DateField, DateTimeField: Date and time handling with chrono integration

Advanced Serialization

  • WritableNestedSerializer: Support updates to nested objects
  • ListSerializer: Serialize collections of objects

Additional Renderers

  • YAMLRenderer: Render data as YAML
  • CSVRenderer: Render data as CSV (for list endpoints)
  • OpenAPIRenderer: Generate OpenAPI/Swagger specifications

Meta Options

  • Field inclusion/exclusion
  • Read-only/write-only fields
  • Custom field mappings
  • Depth control for nested serialization

versioning

Features

✅ Implemented

Core Versioning Strategies

  1. URLPathVersioning - Version detection from URL path

    • Extracts version from path segments (e.g., /v1/users/, /v2.0/api/)
    • Customizable regex patterns for flexible version extraction
    • Pattern configuration with with_pattern() method
    • Default fallback version support
    • Allowed versions validation
    • Examples: /v1/, /v2.0/, /api/v3/

  2. AcceptHeaderVersioning - Version detection from Accept header

    • Parses Accept header media type parameters (e.g., Accept: application/json; version=2.0)
    • Configurable version parameter name
    • Strict version validation
    • Default version fallback
    • Compatible with standard media type negotiation
    • Example: Accept: application/json; version=1.0

  3. QueryParameterVersioning - Version detection from query parameters

    • Extracts version from query string (e.g., ?version=1.0, ?v=2.0)
    • Customizable parameter name with with_version_param()
    • Multiple parameter support
    • Default version fallback
    • Examples: ?version=1.0, ?v=2.0

  4. HostNameVersioning - Version detection from subdomain

    • Extracts version from hostname subdomain (e.g., v1.api.example.com)
    • Customizable regex patterns for hostname parsing
    • Host format configuration with with_host_format()
    • Hostname pattern mapping with with_hostname_pattern()
    • Port handling support
    • Examples: v1.api.example.com, api-v2.example.com

  5. NamespaceVersioning - Version detection from URL namespace

    • Router namespace integration for version extraction
    • Configurable namespace patterns (e.g., /v{version}/)
    • Namespace prefix support with with_namespace_prefix()
    • Router integration methods:
      • extract_version_from_router() - Extract version from router path
      • get_available_versions_from_router() - Get all registered versions
    • Pattern-based version extraction
    • Examples: /v1/users/, /api/v2/posts/

Middleware System

  1. VersioningMiddleware - Automatic version detection and injection

    • Integrates with any BaseVersioning strategy
    • Automatic version extraction from requests
    • Stores version in request extensions
    • Error handling for invalid versions
    • Clone support for middleware composition
    • Zero-cost abstraction over versioning strategies

  2. RequestVersionExt - Type-safe version access from requests

    • version() - Get version as Option<String>
    • version_or() - Get version with fallback default
    • Seamless integration with request extensions
    • Type-safe version retrieval

  3. ApiVersion - Version data type

    • as_str() - Get version as string slice
    • to_string() - Get version as owned String
    • new() - Create new version instance
    • Clone and Debug support

Handler Integration

  1. VersionedHandler - Trait for version-aware handlers

    • handle_versioned() - Handle request with version context
    • supported_versions() - Get list of supported versions
    • supports_version() - Check version support

  2. VersionedHandlerWrapper - Handler trait adapter

    • Makes VersionedHandler compatible with standard Handler trait
    • Automatic version determination
    • Version validation before handling
    • Error handling for unsupported versions

  3. SimpleVersionedHandler - Simple version-to-response mapper

    • Map versions to static responses
    • with_version_response() - Add version-specific response
    • with_default_response() - Set fallback response
    • HashMap-based response lookup

  4. ConfigurableVersionedHandler - Advanced handler configuration

    • Map versions to different handler implementations
    • with_version_handler() - Add version-specific handler
    • with_default_handler() - Set fallback handler
    • Dynamic handler dispatch based on version

  5. VersionedHandlerBuilder - Builder pattern for handlers

    • Fluent API for handler construction
    • Version-handler mapping
    • Default handler configuration
    • Automatic wrapper integration

  6. VersionResponseBuilder - Response builder with version metadata

    • with_data() - Add response data
    • with_field() - Add individual fields
    • with_version_info() - Add version metadata
    • version() - Get current version
    • JSON serialization support

  7. versioned_handler! - Macro for easy handler creation

    • Declarative syntax for version mapping
    • Optional default handler
    • Compile-time version checking

Configuration System

  1. VersioningConfig - Global configuration

    • Centralized versioning settings
    • Strategy configuration
    • Default and allowed versions
    • Strict mode enforcement
    • Version parameter customization
    • Hostname pattern mapping
    • Builder pattern API
    • Serialization/deserialization support

  2. VersioningStrategy - Strategy enumeration

    • Five strategy variants:
      • AcceptHeader - Accept header versioning
      • URLPath { pattern } - URL path with custom pattern
      • QueryParameter { param_name } - Query parameter with custom name
      • HostName { patterns } - Hostname with pattern mapping
      • Namespace { pattern } - Namespace with custom pattern
    • Serde support for configuration files
    • JSON/YAML compatible

  3. VersioningManager - Configuration management

    • Create versioning instances from configuration
    • Dynamic configuration updates
    • config() - Get current configuration
    • versioning() - Get versioning instance
    • update_config() - Update configuration at runtime
    • Environment variable support with from_env()

  4. Environment Configuration - Env var support

    • REINHARDT_VERSIONING_DEFAULT_VERSION - Default version
    • REINHARDT_VERSIONING_ALLOWED_VERSIONS - Comma-separated allowed versions
    • REINHARDT_VERSIONING_STRATEGY - Strategy type
    • REINHARDT_VERSIONING_STRICT_MODE - Enable/disable strict mode

URL Reverse System

  1. VersionedUrlBuilder - Versioned URL construction

    • Build URLs with version in appropriate location
    • Strategy-aware URL generation
    • build() - Build URL with default version
    • build_with_version() - Build URL with specific version
    • build_all_versions() - Build URLs for all allowed versions
    • Support for all five versioning strategies

  2. UrlReverseManager - Multiple builder management

    • Named builder registration
    • Default builder support
    • add_builder() - Register named builder
    • with_default_builder() - Set default builder
    • build_url() - Build URL with named builder
    • build_default_url() - Build URL with default builder
    • build_all_urls() - Build URLs with all builders

  3. ApiDocUrlBuilder - API documentation URL builder

    • OpenAPI schema URLs
    • Swagger UI URLs
    • ReDoc URLs
    • Custom format support
    • Version-specific documentation paths
    • Examples:
      • /v1.0/openapi.json
      • /v2.0/swagger-ui/
      • /v1.0/redoc/

  4. ApiDocFormat - Documentation format enum

    • OpenApi - OpenAPI 3.0 JSON
    • Swagger - Swagger UI
    • ReDoc - ReDoc documentation
    • Custom(String) - Custom format

  5. versioned_url! - Macro for URL building

    • Simple syntax for URL construction
    • Version override support
    • Type-safe URL generation

Testing & Quality

  1. Comprehensive Test Coverage

    • 29+ unit tests across all modules
    • 11+ integration tests
    • All versioning strategies tested
    • Middleware integration tests
    • Handler system tests
    • URL building tests
    • Configuration serialization tests

  2. Test Utilities - test_utils module

    • create_test_request() - Create mock requests for testing
    • Header customization
    • URI customization
    • Reusable across test suites

  3. Full Documentation

    • Comprehensive rustdoc comments
    • Code examples for all public APIs
    • Usage examples in each module
    • Integration examples

Error Handling

  1. VersioningError - Comprehensive error types
    • InvalidAcceptHeader - Malformed Accept header
    • InvalidURLPath - Invalid URL path format
    • InvalidNamespace - Invalid namespace format
    • InvalidHostname - Invalid hostname format
    • InvalidQueryParameter - Invalid query parameter
    • VersionNotAllowed - Version not in allowed list
    • Integration with reinhardt_apps::Error

Traits & Abstractions

  1. BaseVersioning - Core versioning trait
    • determine_version() - Extract version from request
    • default_version() - Get default version
    • allowed_versions() - Get allowed versions
    • is_allowed_version() - Check version validity
    • version_param() - Get version parameter name
    • Async trait for async version detection
    • Send + Sync for thread safety