📜 ResolveSpec 📜

ResolveSpec is a flexible and powerful REST API specification and implementation that provides GraphQL-like capabilities while maintaining REST simplicity. It offers two complementary approaches:

1. ResolveSpec - Body-based API with JSON request options
2. RestHeadSpec - Header-based API where query options are passed via HTTP headers
3. FuncSpec - Header-based API to map and call API's to sql functions.

Both share the same core architecture and provide dynamic data querying, relationship preloading, and complex filtering.

Documentation Generated by LLMs

Table of Contents

• Features
• Installation
• Quick Start
  • ResolveSpec (Body-Based API)
  • RestHeadSpec (Header-Based API)
• Migration from v1.x
• Architecture
• API Structure
• RestHeadSpec Overview
• Example Usage
• Testing
• Additional Packages
• Security Considerations
• What's New

Features

Core Features

• Dynamic Data Querying: Select specific columns and relationships to return
• Relationship Preloading: Load related entities with custom column selection and filters
• Complex Filtering: Apply multiple filters with various operators
• Sorting: Multi-column sort support
• Pagination: Built-in limit/offset and cursor-based pagination (both ResolveSpec and RestHeadSpec)
• Computed Columns: Define virtual columns for complex calculations
• Custom Operators: Add custom SQL conditions when needed
• 🆕 Recursive CRUD Handler: Automatically handle nested object graphs with foreign key resolution and per-record operation control via _request field

Architecture (v2.0+)

• 🆕 Database Agnostic: Works with GORM, Bun, or any database layer through adapters
• 🆕 Router Flexible: Integrates with Gorilla Mux, Gin, Echo, or custom routers
• 🆕 Backward Compatible: Existing code works without changes
• 🆕 Better Testing: Mockable interfaces for easy unit testing

RestHeadSpec (v2.1+)

• 🆕 Header-Based API: All query options passed via HTTP headers instead of request body
• 🆕 Lifecycle Hooks: Before/after hooks for create, read, update, and delete operations
• 🆕 Cursor Pagination: Efficient cursor-based pagination with complex sort support
• 🆕 Multiple Response Formats: Simple, detailed, and Syncfusion-compatible formats
• 🆕 Single Record as Object: Automatically normalize single-element arrays to objects (enabled by default)
• 🆕 Advanced Filtering: Field filters, search operators, AND/OR logic, and custom SQL
• 🆕 Base64 Encoding: Support for base64-encoded header values

Routing & CORS (v3.0+)

• 🆕 Explicit Route Registration: Routes created per registered model instead of dynamic lookups
• 🆕 OPTIONS Method Support: Full OPTIONS method support returning model metadata
• 🆕 CORS Headers: Comprehensive CORS support with all HeadSpec headers allowed
• 🆕 Better Route Control: Customize routes per model with more flexibility

API Structure

URL Patterns

/[schema]/[table_or_entity]/[id]
/[schema]/[table_or_entity]
/[schema]/[function]
/[schema]/[virtual]

Request Format

{
  "operation": "read|create|update|delete",
  "data": {
    // For create/update operations
  },
  "options": {
    "preload": [...],
    "columns": [...],
    "filters": [...],
    "sort": [...],
    "limit": number,
    "offset": number,
    "customOperators": [...],
    "computedColumns": [...]
  }
}

RestHeadSpec: Header-Based API

RestHeadSpec provides an alternative REST API approach where all query options are passed via HTTP headers instead of the request body. This provides cleaner separation between data and metadata.

Quick Example

GET /public/users HTTP/1.1
Host: api.example.com
X-Select-Fields: id,name,email,department_id
X-Preload: department:id,name
X-FieldFilter-Status: active
X-SearchOp-Gte-Age: 18
X-Sort: -created_at,+name
X-Limit: 50
X-DetailApi: true

For complete documentation including setup, headers, lifecycle hooks, cursor pagination, and more, see pkg/restheadspec/README.md.

Example Usage

For detailed examples of reading data, cursor pagination, recursive CRUD operations, filtering, sorting, and more, see pkg/resolvespec/README.md.

Installation

go get github.com/bitechdev/ResolveSpec

Quick Start

ResolveSpec (Body-Based API)

ResolveSpec uses JSON request bodies to specify query options:

import "github.com/bitechdev/ResolveSpec/pkg/resolvespec"

// Create handler
handler := resolvespec.NewHandlerWithGORM(db)
handler.registry.RegisterModel("core.users", &User{})

// Setup routes
router := mux.NewRouter()
resolvespec.SetupMuxRoutes(router, handler, nil)

// Client makes POST request with body:
// POST /core/users
// {
//   "operation": "read",
//   "options": {
//     "columns": ["id", "name", "email"],
//     "filters": [{"column": "status", "operator": "eq", "value": "active"}],
//     "limit": 10
//   }
// }

For complete documentation, see pkg/resolvespec/README.md.

RestHeadSpec (Header-Based API)

RestHeadSpec uses HTTP headers for query options instead of request body:

import "github.com/bitechdev/ResolveSpec/pkg/restheadspec"

// Create handler with GORM
handler := restheadspec.NewHandlerWithGORM(db)

// Register models (schema.table format)
handler.Registry.RegisterModel("public.users", &User{})
handler.Registry.RegisterModel("public.posts", &Post{})

// Setup routes with Mux
router := mux.NewRouter()
restheadspec.SetupMuxRoutes(router, handler, nil)

// Client makes GET request with headers:
// GET /public/users
// X-Select-Fields: id,name,email
// X-FieldFilter-Status: active
// X-Limit: 10
// X-Sort: -created_at
// X-Preload: posts:id,title

For complete documentation, see pkg/restheadspec/README.md.

Migration from v1.x

ResolveSpec v2.0 maintains 100% backward compatibility. For detailed migration instructions, see MIGRATION_GUIDE.md.

Architecture

Two Complementary APIs

┌─────────────────────────────────────────────────────┐
│           ResolveSpec Framework                      │
├─────────────────────┬───────────────────────────────┤
│   ResolveSpec       │      RestHeadSpec             │
│   (Body-based)      │      (Header-based)           │
├─────────────────────┴───────────────────────────────┤
│         Common Core Components                       │
│  • Model Registry  • Filters  • Preloading          │
│  • Sorting  • Pagination  • Type System             │
└──────────────────────┬──────────────────────────────┘
                       ↓
        ┌──────────────────────────────┐
        │   Database Abstraction       │
        │   [GORM] [Bun] [Custom]      │
        └──────────────────────────────┘

Database Abstraction Layer

Your Application Code
        ↓
   Handler (Business Logic)
        ↓
   [Hooks & Middleware] (RestHeadSpec only)
        ↓
   Database Interface
        ↓
   [GormAdapter] [BunAdapter] [CustomAdapter]
        ↓              ↓           ↓
    [GORM]         [Bun]    [Your ORM]

Supported Database Layers

• GORM (default, fully supported)
• Bun (ready to use, included in dependencies)
• Custom ORMs (implement the Database interface)

Supported Routers

• Gorilla Mux (built-in support with SetupRoutes())
• BunRouter (built-in support with SetupBunRouterWithResolveSpec())
• Gin (manual integration, see examples above)
• Echo (manual integration, see examples above)
• Custom Routers (implement request/response adapters)

Testing

ResolveSpec is designed for testability with mockable interfaces. For testing examples and best practices, see the individual package documentation:

• ResolveSpec Testing
• RestHeadSpec Testing
• WebSocketSpec Testing

Continuous Integration

ResolveSpec uses GitHub Actions for automated testing and quality checks. The CI pipeline runs on every push and pull request.

CI/CD Workflow

The project includes automated workflows that:

• Test: Run all tests with race detection and code coverage
• Lint: Check code quality with golangci-lint
• Build: Verify the project builds successfully
• Multi-version: Test against multiple Go versions (1.23.x, 1.24.x)

Running Tests Locally

# Run all tests
go test -v ./...

# Run tests with coverage
go test -v -race -coverprofile=coverage.out ./...

# View coverage report
go tool cover -html=coverage.out

# Run linting
golangci-lint run

Test Files

The project includes comprehensive test coverage:

• Unit Tests: Individual component testing
• Integration Tests: End-to-end API testing
• CRUD Tests: Standalone tests for both ResolveSpec and RestHeadSpec APIs

To run only the CRUD standalone tests:

go test -v ./tests -run TestCRUDStandalone

CI Status

Check the Actions tab on GitHub to see the status of recent CI runs. All tests must pass before merging pull requests.

Badge

Add this badge to display CI status in your fork:

![Tests](https://github.com/bitechdev/ResolveSpec/workflows/Tests/badge.svg)

Additional Packages

ResolveSpec includes several complementary packages that work together to provide a complete web application framework:

Core API Packages

ResolveSpec - Body-Based API

The core body-based REST API with GraphQL-like capabilities.

Key Features:

• JSON request body with operation and options
• Recursive CRUD with nested object support
• Cursor and offset pagination
• Advanced filtering and preloading
• Lifecycle hooks

For complete documentation, see pkg/resolvespec/README.md.

RestHeadSpec - Header-Based API

Alternative REST API where query options are passed via HTTP headers.

Key Features:

• All query options via HTTP headers
• Same capabilities as ResolveSpec
• Cleaner separation of data and metadata
• Ideal for GET requests and caching

For complete documentation, see pkg/restheadspec/README.md.

FuncSpec - Function-Based SQL API

Execute SQL functions and queries through a simple HTTP API with header-based parameters.

Key Features:

• Direct SQL function invocation
• Header-based parameter passing
• Automatic pagination and counting
• Request/response hooks
• Variable substitution support

For complete documentation, see pkg/funcspec/.

Real-Time Communication

WebSocketSpec - WebSocket API

Real-time bidirectional communication with full CRUD operations and subscriptions.

Key Features:

• Persistent WebSocket connections
• Real-time subscriptions to entity changes
• Automatic push notifications
• Full CRUD with filtering and sorting
• Connection lifecycle management

For complete documentation, see pkg/websocketspec/README.md.

MQTTSpec - MQTT-Based API

MQTT-based database operations ideal for IoT and mobile applications.

Key Features:

• Embedded or external MQTT broker support
• QoS 1 (at-least-once delivery)
• Real-time subscriptions
• Multi-tenancy support
• Optimized for unreliable networks

For complete documentation, see pkg/mqttspec/README.md.

Server Components

StaticWeb - Static File Server

Flexible, interface-driven static file server.

Key Features:

• Router-agnostic with standard http.Handler
• Multiple filesystem backends (local, zip, embedded)
• Pluggable cache, MIME, and fallback policies
• Hot-reload support
• 140+ MIME types including modern formats

Quick Example:

import "github.com/bitechdev/ResolveSpec/pkg/server/staticweb"

service := staticweb.NewService(nil)
provider, _ := staticweb.LocalProvider("./public")

service.Mount(staticweb.MountConfig{
    URLPrefix:        "/",
    Provider:         provider,
    FallbackStrategy: staticweb.HTMLFallback("index.html"),
})

router.PathPrefix("/").Handler(service.Handler())

For complete documentation, see pkg/server/staticweb/README.md.

Infrastructure & Utilities

Event Broker

Comprehensive event handling system for real-time event publishing and cross-instance communication.

Key Features:

• Multiple event sources (database, websockets, frontend, system)
• Multiple providers (in-memory, Redis Streams, NATS, PostgreSQL)
• Pattern-based subscriptions
• Automatic CRUD event capture
• Retry logic with exponential backoff
• Prometheus metrics

For complete documentation, see pkg/eventbroker/README.md.

Cache

Caching system with support for in-memory and Redis backends.

For documentation, see pkg/cache/README.md.

Security

Authentication and authorization framework with hooks integration.

For documentation, see pkg/security/README.md.

Middleware

HTTP middleware collection for common tasks (CORS, logging, metrics, etc.).

For documentation, see pkg/middleware/README.md.

OpenAPI

OpenAPI/Swagger documentation generation for ResolveSpec APIs.

For documentation, see pkg/openapi/README.md.

Metrics

Prometheus-compatible metrics collection and exposition.

For documentation, see pkg/metrics/README.md.

Tracing

Distributed tracing with OpenTelemetry support.

For documentation, see pkg/tracing/README.md.

Error Tracking

Error tracking and reporting integration.

For documentation, see pkg/errortracking/README.md.

Configuration

Configuration management with support for multiple formats and environments.

For documentation, see pkg/config/README.md.

Security Considerations

• Implement proper authentication and authorization
• Validate all input parameters
• Use prepared statements (handled by GORM/Bun/your ORM)
• Implement rate limiting
• Control access at schema/entity level
• New: Database abstraction layer provides additional security through interface boundaries

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

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

What's New

v3.0 (Latest - December 2025)

Explicit Route Registration (🆕):

• Breaking Change: Routes are now created explicitly for each registered model
• Better Control: Customize routes per model with more flexibility
• Registration Order: Models must be registered BEFORE calling SetupMuxRoutes/SetupBunRouterRoutes
• Benefits: More flexible routing, easier to add custom routes per model, better performance

OPTIONS Method & CORS Support (🆕):

• OPTIONS Endpoint: Full OPTIONS method support for CORS preflight requests
• Metadata Response: OPTIONS returns model metadata (same as GET /metadata)
• CORS Headers: Comprehensive CORS headers on all responses
• Header Support: All HeadSpec custom headers (X-Select-Fields, X-FieldFilter-*, etc.) allowed
• No Auth on OPTIONS: CORS preflight requests don't require authentication
• Configurable: Customize CORS settings via common.CORSConfig

Migration Notes:

• Update your code to register models BEFORE calling SetupMuxRoutes/SetupBunRouterRoutes
• Routes like /public/users are now created per registered model instead of using dynamic /{schema}/{entity} pattern
• This is a breaking change but provides better control and flexibility

v2.1

Cursor Pagination for ResolveSpec (🆕 Dec 9, 2025):

• Cursor-Based Pagination: Efficient cursor pagination now available in ResolveSpec (body-based API)
• Consistent with RestHeadSpec: Both APIs now support cursor pagination for feature parity
• Multi-Column Sort Support: Works seamlessly with complex sorting requirements
• Better Performance: Improved performance for large datasets compared to offset pagination
• SQL Safety: Proper SQL sanitization for cursor values

Recursive CRUD Handler (🆕 Nov 11, 2025):

• Nested Object Graphs: Automatically handle complex object hierarchies with parent-child relationships
• Foreign Key Resolution: Automatic propagation of parent IDs to child records
• Per-Record Operations: Control create/update/delete operations per record via _request field
• Transaction Safety: All nested operations execute atomically within database transactions
• Relationship Detection: Automatic detection of belongsTo, hasMany, hasOne, and many2many relationships
• Deep Nesting Support: Handle relationships at any depth level
• Mixed Operations: Combine insert, update, and delete operations in a single request

Primary Key Improvements (Nov 11, 2025):

• GetPrimaryKeyName: Enhanced primary key detection for better preload and ID field handling
• Better GORM/Bun Support: Improved compatibility with both ORMs for primary key operations
• Computed Column Support: Fixed computed columns functionality across handlers

Database Adapter Enhancements (Nov 11, 2025):

• Bun ORM Relations: Using Scan model method for better has-many and many-to-many relationship handling
• Model Method Support: Enhanced query building with proper model registration
• Improved Type Safety: Better handling of relationship queries with type-aware scanning

RestHeadSpec - Header-Based REST API:

• Header-Based Querying: All query options via HTTP headers instead of request body
• Lifecycle Hooks: Before/after hooks for create, read, update, delete operations
• Cursor Pagination: Efficient cursor-based pagination with complex sorting
• Advanced Filtering: Field filters, search operators, AND/OR logic
• Multiple Response Formats: Simple, detailed, and Syncfusion-compatible responses
• Single Record as Object: Automatically return single-element arrays as objects (default, toggleable via header)
• Base64 Support: Base64-encoded header values for complex queries
• Type-Aware Filtering: Automatic type detection and conversion for filters

Core Improvements:

• Better model registry with schema.table format support
• Enhanced validation and error handling
• Improved reflection safety
• Fixed COUNT query issues with table aliasing
• Better pointer handling throughout the codebase
• Comprehensive Test Coverage: Added standalone CRUD tests for both ResolveSpec and RestHeadSpec

v2.0

Breaking Changes:

• None! Full backward compatibility maintained

New Features:

• Database Abstraction: Support for GORM, Bun, and custom ORMs
• Router Flexibility: Works with any HTTP router through adapters
• BunRouter Integration: Built-in support for uptrace/bunrouter
• Better Architecture: Clean separation of concerns with interfaces
• Enhanced Testing: Mockable interfaces for comprehensive testing
• Migration Guide: Step-by-step migration instructions

Performance Improvements:

• More efficient query building through interface design
• Reduced coupling between components
• Better memory management with interface boundaries

Acknowledgments

• Inspired by REST, OData, and GraphQL's flexibility
• Header-based approach: Inspired by REST best practices and clean API design
• Database Support: GORM and Bun
• Router Support: Gorilla Mux (built-in), BunRouter, Gin, Echo, and others through adapters
• Slogan generated using DALL-E
• AI used for documentation checking and correction
• Community feedback and contributions that made v2.0 and v2.1 possible