|
|
|
|
@ -1,9 +1,16 @@
|
|
|
|
|
# 📜 ResolveSpec 📜
|
|
|
|
|
|
|
|
|
|
ResolveSpec is a flexible and powerful REST API specification and implementation that provides GraphQL-like capabilities while maintaining REST simplicity. It allows for dynamic data querying, relationship preloading, and complex filtering through a clean, URL-based interface.
|
|
|
|
|
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
|
|
|
|
|
|
|
|
|
|
Both share the same core architecture and provide dynamic data querying, relationship preloading, and complex filtering.
|
|
|
|
|
|
|
|
|
|
**🆕 New in v2.0**: Database-agnostic architecture with support for GORM, Bun, and other ORMs. Router-flexible design works with Gorilla Mux, Gin, Echo, and more.
|
|
|
|
|
|
|
|
|
|
**🆕 New in v2.1**: RestHeadSpec (HeaderSpec) - Header-based REST API with lifecycle hooks, cursor pagination, and advanced filtering.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Table of Contents
|
|
|
|
|
@ -11,30 +18,46 @@ ResolveSpec is a flexible and powerful REST API specification and implementation
|
|
|
|
|
- [Features](#features)
|
|
|
|
|
- [Installation](#installation)
|
|
|
|
|
- [Quick Start](#quick-start)
|
|
|
|
|
- [ResolveSpec (Body-Based API)](#resolvespec-body-based-api)
|
|
|
|
|
- [RestHeadSpec (Header-Based API)](#restheadspec-header-based-api)
|
|
|
|
|
- [Existing Code (Backward Compatible)](#option-1-existing-code-backward-compatible)
|
|
|
|
|
- [New Database-Agnostic API](#option-2-new-database-agnostic-api)
|
|
|
|
|
- [Router Integration](#router-integration)
|
|
|
|
|
- [Migration from v1.x](#migration-from-v1x)
|
|
|
|
|
- [Architecture](#architecture)
|
|
|
|
|
- [API Structure](#api-structure)
|
|
|
|
|
- [RestHeadSpec: Header-Based API](#restheadspec-header-based-api-1)
|
|
|
|
|
- [Lifecycle Hooks](#lifecycle-hooks)
|
|
|
|
|
- [Cursor Pagination](#cursor-pagination)
|
|
|
|
|
- [Example Usage](#example-usage)
|
|
|
|
|
- [Testing](#testing)
|
|
|
|
|
- [What's New in v2.0](#whats-new-in-v20)
|
|
|
|
|
|
|
|
|
|
## 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 and offset support
|
|
|
|
|
- **Pagination**: Built-in limit/offset and cursor-based pagination
|
|
|
|
|
- **Computed Columns**: Define virtual columns for complex calculations
|
|
|
|
|
- **Custom Operators**: Add custom SQL conditions when needed
|
|
|
|
|
|
|
|
|
|
### 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
|
|
|
|
|
- **🆕 Advanced Filtering**: Field filters, search operators, AND/OR logic, and custom SQL
|
|
|
|
|
- **🆕 Base64 Encoding**: Support for base64-encoded header values
|
|
|
|
|
|
|
|
|
|
## API Structure
|
|
|
|
|
|
|
|
|
|
### URL Patterns
|
|
|
|
|
@ -66,6 +89,216 @@ ResolveSpec is a flexible and powerful REST API specification and implementation
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## 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
|
|
|
|
|
|
|
|
|
|
```http
|
|
|
|
|
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
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Setup with GORM
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
import "github.com/bitechdev/ResolveSpec/pkg/restheadspec"
|
|
|
|
|
import "github.com/gorilla/mux"
|
|
|
|
|
|
|
|
|
|
// Create handler
|
|
|
|
|
handler := restheadspec.NewHandlerWithGORM(db)
|
|
|
|
|
|
|
|
|
|
// Register models using schema.table format
|
|
|
|
|
handler.Registry.RegisterModel("public.users", &User{})
|
|
|
|
|
handler.Registry.RegisterModel("public.posts", &Post{})
|
|
|
|
|
|
|
|
|
|
// Setup routes
|
|
|
|
|
router := mux.NewRouter()
|
|
|
|
|
restheadspec.SetupMuxRoutes(router, handler)
|
|
|
|
|
|
|
|
|
|
// Start server
|
|
|
|
|
http.ListenAndServe(":8080", router)
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Setup with Bun ORM
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
import "github.com/bitechdev/ResolveSpec/pkg/restheadspec"
|
|
|
|
|
import "github.com/uptrace/bun"
|
|
|
|
|
|
|
|
|
|
// Create handler with Bun
|
|
|
|
|
handler := restheadspec.NewHandlerWithBun(bunDB)
|
|
|
|
|
|
|
|
|
|
// Register models
|
|
|
|
|
handler.Registry.RegisterModel("public.users", &User{})
|
|
|
|
|
|
|
|
|
|
// Setup routes (same as GORM)
|
|
|
|
|
router := mux.NewRouter()
|
|
|
|
|
restheadspec.SetupMuxRoutes(router, handler)
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Common Headers
|
|
|
|
|
|
|
|
|
|
| Header | Description | Example |
|
|
|
|
|
|--------|-------------|---------|
|
|
|
|
|
| `X-Select-Fields` | Columns to include | `id,name,email` |
|
|
|
|
|
| `X-Not-Select-Fields` | Columns to exclude | `password,internal_notes` |
|
|
|
|
|
| `X-FieldFilter-{col}` | Exact match filter | `X-FieldFilter-Status: active` |
|
|
|
|
|
| `X-SearchFilter-{col}` | Fuzzy search (ILIKE) | `X-SearchFilter-Name: john` |
|
|
|
|
|
| `X-SearchOp-{op}-{col}` | Filter with operator | `X-SearchOp-Gte-Age: 18` |
|
|
|
|
|
| `X-Preload` | Preload relations | `posts:id,title` |
|
|
|
|
|
| `X-Sort` | Sort columns | `-created_at,+name` |
|
|
|
|
|
| `X-Limit` | Limit results | `50` |
|
|
|
|
|
| `X-Offset` | Offset for pagination | `100` |
|
|
|
|
|
| `X-Clean-JSON` | Remove null/empty fields | `true` |
|
|
|
|
|
|
|
|
|
|
**Available Operators**: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains`, `startswith`, `endswith`, `between`, `betweeninclusive`, `in`, `empty`, `notempty`
|
|
|
|
|
|
|
|
|
|
For complete header documentation, see [pkg/restheadspec/HEADERS.md](pkg/restheadspec/HEADERS.md).
|
|
|
|
|
|
|
|
|
|
### Lifecycle Hooks
|
|
|
|
|
|
|
|
|
|
RestHeadSpec supports lifecycle hooks for all CRUD operations:
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
import "github.com/bitechdev/ResolveSpec/pkg/restheadspec"
|
|
|
|
|
|
|
|
|
|
// Create handler
|
|
|
|
|
handler := restheadspec.NewHandlerWithGORM(db)
|
|
|
|
|
|
|
|
|
|
// Register a before-read hook (e.g., for authorization)
|
|
|
|
|
handler.Hooks.Register(restheadspec.BeforeRead, func(ctx *restheadspec.HookContext) error {
|
|
|
|
|
// Check permissions
|
|
|
|
|
if !userHasPermission(ctx.Context, ctx.Entity) {
|
|
|
|
|
return fmt.Errorf("unauthorized access to %s", ctx.Entity)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Modify query options
|
|
|
|
|
ctx.Options.Limit = ptr(100) // Enforce max limit
|
|
|
|
|
|
|
|
|
|
return nil
|
|
|
|
|
})
|
|
|
|
|
|
|
|
|
|
// Register an after-read hook (e.g., for data transformation)
|
|
|
|
|
handler.Hooks.Register(restheadspec.AfterRead, func(ctx *restheadspec.HookContext) error {
|
|
|
|
|
// Transform or filter results
|
|
|
|
|
if users, ok := ctx.Result.([]User); ok {
|
|
|
|
|
for i := range users {
|
|
|
|
|
users[i].Email = maskEmail(users[i].Email)
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
return nil
|
|
|
|
|
})
|
|
|
|
|
|
|
|
|
|
// Register a before-create hook (e.g., for validation)
|
|
|
|
|
handler.Hooks.Register(restheadspec.BeforeCreate, func(ctx *restheadspec.HookContext) error {
|
|
|
|
|
// Validate data
|
|
|
|
|
if user, ok := ctx.Data.(*User); ok {
|
|
|
|
|
if user.Email == "" {
|
|
|
|
|
return fmt.Errorf("email is required")
|
|
|
|
|
}
|
|
|
|
|
// Add timestamps
|
|
|
|
|
user.CreatedAt = time.Now()
|
|
|
|
|
}
|
|
|
|
|
return nil
|
|
|
|
|
})
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**Available Hook Types**:
|
|
|
|
|
- `BeforeRead`, `AfterRead`
|
|
|
|
|
- `BeforeCreate`, `AfterCreate`
|
|
|
|
|
- `BeforeUpdate`, `AfterUpdate`
|
|
|
|
|
- `BeforeDelete`, `AfterDelete`
|
|
|
|
|
|
|
|
|
|
**HookContext** provides:
|
|
|
|
|
- `Context`: Request context
|
|
|
|
|
- `Handler`: Access to handler, database, and registry
|
|
|
|
|
- `Schema`, `Entity`, `TableName`: Request info
|
|
|
|
|
- `Model`: The registered model type
|
|
|
|
|
- `Options`: Parsed request options (filters, sorting, etc.)
|
|
|
|
|
- `ID`: Record ID (for single-record operations)
|
|
|
|
|
- `Data`: Request data (for create/update)
|
|
|
|
|
- `Result`: Operation result (for after hooks)
|
|
|
|
|
- `Writer`: Response writer (allows hooks to modify response)
|
|
|
|
|
|
|
|
|
|
### Cursor Pagination
|
|
|
|
|
|
|
|
|
|
RestHeadSpec supports efficient cursor-based pagination for large datasets:
|
|
|
|
|
|
|
|
|
|
```http
|
|
|
|
|
GET /public/posts HTTP/1.1
|
|
|
|
|
X-Sort: -created_at,+id
|
|
|
|
|
X-Limit: 50
|
|
|
|
|
X-Cursor-Forward: <cursor_token>
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**How it works**:
|
|
|
|
|
1. First request returns results + cursor token in response
|
|
|
|
|
2. Subsequent requests use `X-Cursor-Forward` or `X-Cursor-Backward`
|
|
|
|
|
3. Cursor maintains consistent ordering even with data changes
|
|
|
|
|
4. Supports complex multi-column sorting
|
|
|
|
|
|
|
|
|
|
**Benefits over offset pagination**:
|
|
|
|
|
- Consistent results when data changes
|
|
|
|
|
- Better performance for large offsets
|
|
|
|
|
- Prevents "skipped" or duplicate records
|
|
|
|
|
- Works with complex sort expressions
|
|
|
|
|
|
|
|
|
|
**Example with hooks**:
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
// Enable cursor pagination in a hook
|
|
|
|
|
handler.Hooks.Register(restheadspec.BeforeRead, func(ctx *restheadspec.HookContext) error {
|
|
|
|
|
// For large tables, enforce cursor pagination
|
|
|
|
|
if ctx.Entity == "posts" && ctx.Options.Offset != nil && *ctx.Options.Offset > 1000 {
|
|
|
|
|
return fmt.Errorf("use cursor pagination for large offsets")
|
|
|
|
|
}
|
|
|
|
|
return nil
|
|
|
|
|
})
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Response Formats
|
|
|
|
|
|
|
|
|
|
RestHeadSpec supports multiple response formats:
|
|
|
|
|
|
|
|
|
|
**1. Simple Format** (`X-SimpleApi: true`):
|
|
|
|
|
```json
|
|
|
|
|
[
|
|
|
|
|
{ "id": 1, "name": "John" },
|
|
|
|
|
{ "id": 2, "name": "Jane" }
|
|
|
|
|
]
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**2. Detail Format** (`X-DetailApi: true`, default):
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"success": true,
|
|
|
|
|
"data": [...],
|
|
|
|
|
"metadata": {
|
|
|
|
|
"total": 100,
|
|
|
|
|
"filtered": 100,
|
|
|
|
|
"limit": 50,
|
|
|
|
|
"offset": 0
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**3. Syncfusion Format** (`X-Syncfusion: true`):
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"result": [...],
|
|
|
|
|
"count": 100
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Example Usage
|
|
|
|
|
|
|
|
|
|
### Reading Data with Related Entities
|
|
|
|
|
@ -110,17 +343,73 @@ POST /core/users
|
|
|
|
|
## Installation
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
go get github.com/Warky-Devs/ResolveSpec
|
|
|
|
|
go get github.com/bitechdev/ResolveSpec
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Quick Start
|
|
|
|
|
|
|
|
|
|
### ResolveSpec (Body-Based API)
|
|
|
|
|
|
|
|
|
|
ResolveSpec uses JSON request bodies to specify query options:
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
import "github.com/bitechdev/ResolveSpec/pkg/resolvespec"
|
|
|
|
|
|
|
|
|
|
// Create handler
|
|
|
|
|
handler := resolvespec.NewAPIHandler(gormDB)
|
|
|
|
|
handler.RegisterModel("core", "users", &User{})
|
|
|
|
|
|
|
|
|
|
// Setup routes
|
|
|
|
|
router := mux.NewRouter()
|
|
|
|
|
resolvespec.SetupRoutes(router, handler)
|
|
|
|
|
|
|
|
|
|
// 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
|
|
|
|
|
// }
|
|
|
|
|
// }
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### RestHeadSpec (Header-Based API)
|
|
|
|
|
|
|
|
|
|
RestHeadSpec uses HTTP headers for query options instead of request body:
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
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
|
|
|
|
|
muxRouter := mux.NewRouter()
|
|
|
|
|
restheadspec.SetupMuxRoutes(muxRouter, handler)
|
|
|
|
|
|
|
|
|
|
// 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
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
See [RestHeadSpec: Header-Based API](#restheadspec-header-based-api-1) for complete header documentation.
|
|
|
|
|
|
|
|
|
|
### Option 1: Existing Code (Backward Compatible)
|
|
|
|
|
|
|
|
|
|
Your existing code continues to work without any changes:
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
import "github.com/Warky-Devs/ResolveSpec/pkg/resolvespec"
|
|
|
|
|
import "github.com/bitechdev/ResolveSpec/pkg/resolvespec"
|
|
|
|
|
|
|
|
|
|
// This still works exactly as before
|
|
|
|
|
handler := resolvespec.NewAPIHandler(gormDB)
|
|
|
|
|
@ -131,12 +420,36 @@ handler.RegisterModel("core", "users", &User{})
|
|
|
|
|
|
|
|
|
|
ResolveSpec v2.0 introduces a new database and router abstraction layer while maintaining **100% backward compatibility**. Your existing code will continue to work without any changes.
|
|
|
|
|
|
|
|
|
|
### Repository Path Migration
|
|
|
|
|
|
|
|
|
|
**IMPORTANT**: The repository has moved from `github.com/Warky-Devs/ResolveSpec` to `github.com/bitechdev/ResolveSpec`.
|
|
|
|
|
|
|
|
|
|
To update your imports:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# Update go.mod
|
|
|
|
|
go mod edit -replace github.com/Warky-Devs/ResolveSpec=github.com/bitechdev/ResolveSpec@latest
|
|
|
|
|
go mod tidy
|
|
|
|
|
|
|
|
|
|
# Or update imports manually in your code
|
|
|
|
|
# Old: import "github.com/Warky-Devs/ResolveSpec/pkg/resolvespec"
|
|
|
|
|
# New: import "github.com/bitechdev/ResolveSpec/pkg/resolvespec"
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Alternatively, use find and replace in your project:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
find . -type f -name "*.go" -exec sed -i 's|github.com/Warky-Devs/ResolveSpec|github.com/bitechdev/ResolveSpec|g' {} +
|
|
|
|
|
go mod tidy
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Migration Timeline
|
|
|
|
|
|
|
|
|
|
1. **Phase 1**: Continue using existing API (no changes needed)
|
|
|
|
|
2. **Phase 2**: Gradually adopt new constructors when convenient
|
|
|
|
|
3. **Phase 3**: Switch to interface-based approach for new features
|
|
|
|
|
4. **Phase 4**: Optionally switch database backends
|
|
|
|
|
1. **Phase 1**: Update repository path (see above)
|
|
|
|
|
2. **Phase 2**: Continue using existing API (no changes needed)
|
|
|
|
|
3. **Phase 3**: Gradually adopt new constructors when convenient
|
|
|
|
|
4. **Phase 4**: Switch to interface-based approach for new features
|
|
|
|
|
5. **Phase 5**: Optionally switch database backends or try RestHeadSpec
|
|
|
|
|
|
|
|
|
|
### Detailed Migration Guide
|
|
|
|
|
|
|
|
|
|
@ -144,6 +457,26 @@ For detailed migration instructions, examples, and best practices, see [MIGRATIO
|
|
|
|
|
|
|
|
|
|
## 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
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
@ -151,6 +484,8 @@ Your Application Code
|
|
|
|
|
↓
|
|
|
|
|
Handler (Business Logic)
|
|
|
|
|
↓
|
|
|
|
|
[Hooks & Middleware] (RestHeadSpec only)
|
|
|
|
|
↓
|
|
|
|
|
Database Interface
|
|
|
|
|
↓
|
|
|
|
|
[GormAdapter] [BunAdapter] [CustomAdapter]
|
|
|
|
|
@ -176,7 +511,7 @@ Your Application Code
|
|
|
|
|
|
|
|
|
|
#### With GORM (Recommended Migration Path)
|
|
|
|
|
```go
|
|
|
|
|
import "github.com/Warky-Devs/ResolveSpec/pkg/resolvespec"
|
|
|
|
|
import "github.com/bitechdev/ResolveSpec/pkg/resolvespec"
|
|
|
|
|
|
|
|
|
|
// Create database adapter
|
|
|
|
|
dbAdapter := resolvespec.NewGormAdapter(gormDB)
|
|
|
|
|
@ -192,7 +527,7 @@ handler := resolvespec.NewHandler(dbAdapter, registry)
|
|
|
|
|
|
|
|
|
|
#### With Bun ORM
|
|
|
|
|
```go
|
|
|
|
|
import "github.com/Warky-Devs/ResolveSpec/pkg/resolvespec"
|
|
|
|
|
import "github.com/bitechdev/ResolveSpec/pkg/resolvespec"
|
|
|
|
|
import "github.com/uptrace/bun"
|
|
|
|
|
|
|
|
|
|
// Create Bun adapter (Bun dependency already included)
|
|
|
|
|
@ -415,12 +750,32 @@ func TestHandler(t *testing.T) {
|
|
|
|
|
|
|
|
|
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
|
|
|
|
|
|
|
|
## What's New in v2.0
|
|
|
|
|
## What's New
|
|
|
|
|
|
|
|
|
|
### Breaking Changes
|
|
|
|
|
### v2.1 (Latest)
|
|
|
|
|
|
|
|
|
|
**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
|
|
|
|
|
- **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
|
|
|
|
|
|
|
|
|
|
### v2.0
|
|
|
|
|
|
|
|
|
|
**Breaking Changes**:
|
|
|
|
|
- **None!** Full backward compatibility maintained
|
|
|
|
|
|
|
|
|
|
### New Features
|
|
|
|
|
**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
|
|
|
|
|
@ -428,7 +783,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
|
|
|
|
|
- **Enhanced Testing**: Mockable interfaces for comprehensive testing
|
|
|
|
|
- **Migration Guide**: Step-by-step migration instructions
|
|
|
|
|
|
|
|
|
|
### Performance Improvements
|
|
|
|
|
**Performance Improvements**:
|
|
|
|
|
- More efficient query building through interface design
|
|
|
|
|
- Reduced coupling between components
|
|
|
|
|
- Better memory management with interface boundaries
|
|
|
|
|
@ -436,8 +791,9 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
|
|
|
|
|
## Acknowledgments
|
|
|
|
|
|
|
|
|
|
- Inspired by REST, OData, and GraphQL's flexibility
|
|
|
|
|
- **Header-based approach**: Inspired by REST best practices and clean API design
|
|
|
|
|
- **Database Support**: [GORM](https://gorm.io) and [Bun](https://bun.uptrace.dev/)
|
|
|
|
|
- **Router Support**: Gorilla Mux (built-in), Gin, Echo, and others through adapters
|
|
|
|
|
- **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 possible
|
|
|
|
|
- Community feedback and contributions that made v2.0 and v2.1 possible
|
Hein