GoREST

🚀 GoREST is a Go library for building type-safe REST APIs in Go from your existing database schema or from scratch.

✨ Features

• 🛠 Codegen REST endpoints, resource DTOs and models for each table
• 🔎 Auto-discovery of tables, relations, columns & types
• ⚡ Type-safe generic CRUD operations with hooks system
• 🔐 Full DTO support with field-level control (dto tags)
• 🔑 JWT authentication with context-aware plugins
• 🎭 Hook layer to add your business logic and override any API layer
• 🧩 Modular plugin system that can add features, override some or all existing endpoints or even CLI commands
• ✅ Security best practices, rate limiting, CORS and many more configurable core middleware
• 🌐 JSON-LD support with semantic web context (@context, @type, @id)
• 🔗 Advanced resource deserialization with IRI and optional on demand relations
• 🔍 Advanced serialization, filtering & ordering
• 📄 Page based pagination with Hydra collections
• 👨🏻‍💻 DAL, migrations and fixtures with PostgreSQL, MySQL and SQLite engines support
• 🛡️ Production grade errors and processes management
• 🐳 Docker and Kubernetes support
• 🧪 Full test coverage with automated testing
• 💚 Status check endpoint (/status)
• 📜 OpenAPI 3 spec generation in html or any format

---

🚀 Quick Start

1. Create Your Project

mkdir my-api && cd my-api
go mod init github.com/yourusername/my-api
go get github.com/nicolasbonnici/gorest@latest

2. Configure Your API

Create gorest.yaml in your project root:

server:
  scheme: "${SERVER_SCHEME:-http}"
  host: "${SERVER_HOST:-localhost}"
  port: "${SERVER_PORT:-8000}"
  environment: "${ENV:-development}"

database:
  url: "${DATABASE_URL}"

pagination:
  default_limit: "${PAGINATION_DEFAULT_LIMIT:-10}"
  max_limit: "${PAGINATION_MAX_LIMIT:-1000}"

plugins:
  - name: auth
    enabled: true
    config:
      jwt_secret: "${JWT_SECRET}"
      jwt_ttl: 900

codegen:
  output:
    models: "generated/models"
    resources: "generated/resources"
    dtos: "generated/dtos"
    openapi: "generated/openapi"
    config: "generated/config"

  enums:
    enabled: true

  auth:
    enabled: true
    defaults:
      GET: true
      POST: true
      PUT: true
      DELETE: true
    endpoints:
      - name: posts
        GET: false

Set required environment variables:

# Required (no defaults)
export DATABASE_URL="postgres://user:pass@localhost:5432/mydb?sslmode=require"
export JWT_SECRET=$(openssl rand -base64 32)

# Optional (defaults shown in gorest.yaml above)
export ENV="production"              # default: development
export SERVER_SCHEME="https"         # default: http
export SERVER_HOST="api.example.com" # default: localhost
export SERVER_PORT="8080"            # default: 8000
export PAGINATION_DEFAULT_LIMIT="20" # default: 10
export PAGINATION_MAX_LIMIT="5000"   # default: 1000

Or use a .env file (dotenv support):

# Required
DATABASE_URL=postgres://user:pass@localhost:5432/mydb?sslmode=require
JWT_SECRET=your-secret-key-here

# Optional (override defaults)
ENV=production
SERVER_SCHEME=https
SERVER_HOST=api.example.com
SERVER_PORT=8080
PAGINATION_DEFAULT_LIMIT=20
PAGINATION_MAX_LIMIT=5000

📚 Full configuration documentation →

Environment Variable Interpolation

GoREST supports bash-style environment variable interpolation with default fallback values:

Syntax:

• ${VAR} - Use environment variable VAR (leaves ${VAR} unchanged if not set)
• ${VAR:-default} - Use environment variable VAR, or "default" if not set

Examples:

server:
  # Will use environment variable or fallback to default
  port: "${SERVER_PORT:-8000}"
  host: "${SERVER_HOST:-localhost}"

  # Required variable (no default)
  environment: "${ENV}"

database:
  # Complex defaults work too
  url: "${DATABASE_URL:-postgres://user:pass@localhost:5432/dev?sslmode=disable}"

pagination:
  # Numeric defaults
  default_limit: "${PAGINATION_DEFAULT_LIMIT:-10}"
  max_limit: "${PAGINATION_MAX_LIMIT:-1000}"

plugins:
  - name: auth
    config:
      # Empty default
      jwt_secret: "${JWT_SECRET:-}"

Behavior:

• If the environment variable is set (even to an empty string), its value is used
• If the environment variable is not set and a default is provided, the default is used
• If the environment variable is not set and no default is provided, the original ${VAR} string remains

Note: Environment variable interpolation only works for string fields in the configuration. Integer fields like port, default_limit, and max_limit must be specified as numeric values directly in the YAML file.

3. Generate Code from Your Database

go run github.com/nicolasbonnici/gorest/cmd/codegen@latest all

4. Create Your Main Application

package main

import (
    "github.com/yourusername/my-api/generated/resources"
    "github.com/nicolasbonnici/gorest"
)

func main() {
    cfg := gorest.Config{
        ConfigPath:     ".",
        RegisterRoutes: resources.RegisterGeneratedRoutes,
    }
    gorest.Start(cfg)
}

5. Run Your API

go run main.go

Your API is now running at: ${SERVER_SCHEME}://${SERVER_HOST}:${SERVER_PORT}/

• 📚 API specs: ${SERVER_SCHEME}://${SERVER_HOST}:${SERVER_PORT}/openapi
• 💚 Status: ${SERVER_SCHEME}://${SERVER_HOST}:${SERVER_PORT}/status

(With default values: http://localhost:8000/)

---

📦 Using GoREST as a Library

Import GoREST packages directly in your Go projects:

go get github.com/nicolasbonnici/gorest@latest

Available Packages

Package	Description
crud	Type-safe CRUD operations with hooks
database	Multi-database abstraction
expand	Relation expansion (IRI to object)
filter	Query filtering & ordering
serializer	JSON-LD response serialization
hooks	Lifecycle hooks for business logic
plugin	Plugin interfaces
pluginloader	Plugin factory & loading
pagination	Hydra-compliant pagination
response	HTTP response helpers
migrations	Database migration system
fixtures	Test fixture management

Example

import (
    "github.com/gofiber/fiber/v2"
    "github.com/nicolasbonnici/gorest/database"
    "github.com/nicolasbonnici/gorest/crud"
    auth "github.com/nicolasbonnici/gorest-auth"
)

type User struct {
    ID    string `json:"id" db:"id"`
    Email string `json:"email" db:"email"`
}

func (User) TableName() string { return "users" }

func main() {
    db, _ := database.Open("postgres", "postgres://...")
    defer db.Close()

    userCRUD := crud.New[User](db)
    app := fiber.New()

    app.Get("/users", auth.RequireAuth("secret", func(c *fiber.Ctx) error {
        ctx := auth.Context(c)
        result, _ := userCRUD.GetAllPaginated(ctx, crud.PaginationOptions{Limit: 10})
        return c.JSON(result.Items)
    }))

    app.Listen(":8000")
}

📚 Full API documentation on pkg.go.dev

---

📚 Core Documentation

Configuration & Setup

• Configuration → - YAML configuration, environment overrides, and templates
• Plugins → - Plugin system, built-in plugins, and custom plugin creation

Data Management

• DTOs & Field Control → - Control field visibility with dto tags
• Filtering & Ordering → - Query filtering, comparison operators, and ordering
• Relation Expansion → - Expand IRI references to full nested objects
• JSON-LD Support → - Semantic web support and content negotiation

Business Logic

• Hooks System → - Lifecycle hooks for custom business logic
• Database Migrations → - Migration system with multi-database support
• Fixtures → - Test fixture management

---

🔍 Quick Examples

Filtering & Ordering

# Filter by status
GET /todos?status=active

# Multiple filters with comparison
GET /todos?status=active&priority[gte]=5

# Order results
GET /todos?order[created_at]=desc

# Combine all
GET /todos?status=active&priority[gte]=5&order[created_at]=desc&limit=10

📚 Full filtering documentation →

Expand Relations

# IRI reference (default)
GET /todos/123
# Returns: { "user": "/users/456", ... }

# Expand to full object
GET /todos/123?expand[]=user
# Returns: { "user": { "id": "456", "name": "Alice", ... }, ... }

📚 Full expansion documentation →

JSON-LD Support

# Regular JSON
curl -H "Accept: application/json" http://localhost:8000/todos/123

# JSON-LD with semantic context
curl -H "Accept: application/ld+json" http://localhost:8000/todos/123

📚 Full JSON-LD documentation →

---

📂 Project Structure

Generated Project

my-api/
├── gorest.yaml              # Configuration
├── main.go                  # Your application
└── generated/
    ├── models/              # DB models
    ├── resources/           # REST handlers
    ├── dtos/                # Data transfer objects
    └── openapi/             # OpenAPI schema

GoREST Library

gorest/
├── crud/                    # Generic CRUD
├── database/                # Multi-DB abstraction
│   ├── postgres/
│   ├── mysql/
│   └── sqlite/
├── migrations/              # Migration system
├── fixtures/                # Fixture management
├── expand/                  # Relation expansion
├── filter/                  # Query filtering
├── serializer/              # JSON-LD serialization
├── codegen/                 # Code generation
├── hooks/                   # Lifecycle hooks
├── plugin/                  # Plugin interfaces
├── pluginloader/            # Plugin loading
├── middleware/              # Core middleware
├── pagination/              # Hydra pagination
├── response/                # HTTP helpers
└── cmd/codegen/             # CLI tool

---

🛠 Development Commands

# Code Generation
make codegen          # Run all code generation
make codegen-models   # Generate models only
make codegen-resources # Generate resources & DTOs only
make codegen-openapi  # Generate OpenAPI schema only

# Testing
make test-up          # Start test databases
make test-schema      # Load test schema
make test             # Run all tests
make test-coverage    # Run tests with coverage

# Benchmarking
make benchmark        # Run API performance benchmarks

---

🚀 Production Deployment

Docker

services:
  api:
    build: .
    ports: ["8000:8000"]
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - JWT_SECRET=${JWT_SECRET}
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/status"]
      interval: 30s

Nginx Reverse Proxy

upstream gorest {
    server localhost:8000;
}

server {
    listen 443 ssl;
    server_name api.example.com;

    location / {
        proxy_pass http://gorest;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Kubernetes Health Checks

livenessProbe:
  httpGet:
    path: /status
    port: 8000
  initialDelaySeconds: 10
  periodSeconds: 30

---

🔒 Security

• Passwords: bcrypt hashing with automatic salts
• JWT: 32+ character secrets required
• CORS: Configurable origins
• Rate Limiting: Configurable per-IP limits
• SQL Injection: Parameterized queries
• Input Validation: go-playground/validator support
• Security Headers: X-Frame-Options, CSP, HSTS, etc.

---

🤝 Contributing

See CONTRIBUTING.md for guidelines.

Quick start:

git clone https://github.com/YOUR_USERNAME/gorest.git
cd gorest
make test-up && make test-schema && make test

---

📋 Changelog

See CHANGELOG.md for release history.

---

📜 License

MIT – free to use in your projects 🚀