Home

🏠 EasyREST

EasyREST turns your relational database into a fully featured, secure RESTful CRUD microservice - no boilerplate code required. Think of it as PostgREST, but not limited to PostgreSQL: out of the box, it works with SQLite, MySQL, PostgreSQL, and adds built‑in ETag caching.

---

🎯 The Problem

Building a production‑ready CRUD API often involves:

• Writing tedious boilerplate for each table and operation
• Implementing secure authentication & authorization (e.g. JWT)
• Sanitizing and validating user inputs to prevent SQL injection
• Adding filtering, sorting, paging, and aggregation endpoints
• Managing database‑specific drivers and connection pools
• Implementing caching or ETag logic for performance

Developers shouldn’t have to re‑solve these common challenges every time they spin up a new service.

---

🏗️ How It Works (Architecture)

flowchart TD
    A[HTTP Request] -->|REST API| B[EasyREST Server]
    B --> C{Authentication}
    C -- Authenticated --> D[Process Request]
    C -- Failed/No Auth --> E[401/403 Response]
    E --> N[HTTP Response]
    D -- Validate Scopes & Params --> D_VALID
    D_VALID -- Valid --> X{Apply Context?}
    D_VALID -- Invalid --> E2[400/403 Response]
    E2 --> N
    X -- Yes --> Y[Replace request.* and erctx.* values]
    X -- No --> Z[Send as is]
    Y --> J[Plugin Client RPC Call]
    Z --> J[Plugin Client RPC Call]
    J --> K["DB Plugin (e.g., SQLite, Postgres, MySQL, etc)"]
    K --> F[Build SQL Query]
    F --> L[Database]
    L --> M[Return Results to DB Plugin]
    M --> J2[Return Results to Plugin Client RPC Call]
    J2 --> B2[Return to EasyREST Server]
    B2 --> N[HTTP Response]

    subgraph "Authentication Layer"
        C
        subgraph "Auth Plugins (Optional)"
            P_Auth[Auth Plugin 1 e.g. JWT]
            P_Auth2[Auth Plugin 2 e.g. OIDC]
        end
        C -->|Via Auth Plugins or Internal| P_Auth
        C -->|Via Auth Plugins or Internal| P_Auth2
        P_Auth ----> C
        P_Auth2 ----> C
    end

Loading

1. EasyREST Server sits in front of your database.
2. It validates JWT tokens and request parameters.
3. It injects context (headers, claims, timezone, Prefer) into queries.
4. It hands off sanitized SQL to a lightweight plugin (SQLite/MySQL/Postgres).
5. Results flow back as JSON (or CSV/XML/form‑URL), with ETag headers for caching.

---

💾 Supported Backends & Caching

• SQLite (built in)
• MySQL
• PostgreSQL
• Redis and Valkey (as an external CachePlugin)

You can mix & match: use SQLite for dev, Postgres in prod, and Redis for ETag caching.

---

⚙️ Key Features

• CRUD & Aggregations via simple URL parameters
• Filtering (where.eq., where.gt., where.in., …) all joined with AND
• Sorting (orderBy=name,-created_at), Paging (limit & offset)
• Context Variables: inject JWT claims (erctx.claims_sub), headers, timezone into SQL
• Transaction Control: Prefer: tx=rollback for safe dry‑runs
• Content Negotiation: JSON, CSV, XML, form‑URL
• ETag & Conditional Requests: built‑in caching & optimistic locking
• Plugin System: write new DB or cache plugins with minimal Go code

---

🚀 User Cases

1. Instant Internal Admin API
   Spin up EasyREST on your legacy MySQL database to give your frontend a secure, documented REST API in minutes—no new code.

2. Multi‑Tenant SaaS
   Use PostgreSQL with row‑level security triggers: inject the tenant ID from JWT claims into every query via erctx.tenant_id, enforcing data isolation.

3. Data Reporting Service
   Expose aggregated metrics (sum, avg, count) on your SQLite analytics DB, add Prefer: tx=rollback for safe preview queries.

4. Cache‑Backed Read API
   Pair with Redis CachePlugin to cache heavy GET requests with ETags, reducing load on your Postgres reporting database.

---