fauxrest

Pseudo-REST Static API Generator — Compile raw JSON datasets into structured, production-ready static API endpoints deployable directly to cost-effective, infinitely scalable CDNs (GitHub Pages, Cloudflare Pages, Netlify, AWS S3, etc.).

fauxrest is a zero-maintenance, blazingly fast command-line utility written in Rust. It eliminates the need for dynamic server processes (such as Node.js or Python) and databases for read-only APIs, enabling infinite scalability and sub-millisecond response times at zero hosting cost.

---

🚀 Features

• Two Configuration Tiers: From zero-config auto-inference (Tier 1) to shorthand JSON routes (Tier 2).
• Flexible Routing Patterns: Support Single Object, Collections (Lists), Item Details (via URL parameters), and Grouping transformations out of the box.
• Advanced Data Cleaning: Deep JSONPath extraction, along with robust sanitization using pick (allowlist) and omit (denylist).
• Multi-Platform Target Formats: Output formats tailored for all static hosting environments, supporting trailing slashes, directory index resolutions, extensionless files, or fully bundled files.
• Asset Bundling & Path Rewriting: Scans compilation output for local asset references (e.g., images), copies them to the distribution folder, and rewrites path links safely.

---

⚓️ Installation

🍺 Homebrew

To install fauxrest into your local environment, type the following command.

# install fauxrest
brew install tamada/tap/faurest

📦 Cargo

The fauxrest can be installed through cargo.

cargo install fauxrest

🐳 Container image

Fauxrest also supports container images distributed on Quay.io. The following example uses docker command, however, you can replace it to your favorit container runner such as podman, finch, apple/container, and/or WSL Container.

docker run -it --rm -v $PWD:/opt quay.io/tama5/faurest:latest 

Options and arguments should follow the above command.

💪 Compile yourself

To compile fauxrest from source, ensure you have Rust installed.

# Clone the repository
git clone https://github.com/username/fauxrest.git
cd fauxrest

# Build in release mode
cargo build --release

The compiled binary will be located in target/release/fauxrest.

---

🚦 Quick Start (Zero-Config Mode)

No configuration files are needed. Organize your JSON data into a directory:

data/
├── profile.json       # direct single object
└── users.json         # list of user objects with "id"

Then run fauxrest:

fauxrest data -d dist

fauxrest will scan ./data, infer the routes, and output:

dist/
├── profile/
│   └── index.json     # Resolves to /profile
└── users/
    ├── index.json     # Resolves to /users
    ├── 1/
    │   └── index.json # Resolves to /users/1 (derived from ID)
    └── 2/
        └── index.json # Resolves to /users/2 (derived from ID)

---

🛠️ Configuration Tiers

Tier 1: Zero-Config (Convention over Configuration)

• Object files (profile.json): Mapped to /profile.
• Array files (users.json) are mapped to /users/index.json (list view), and if elements contain an id field, individual items map to /users/:id (detail view).

Tier 2: Shorthand Routing (_config.json)

For basic routing overrides, create a simple _config.json configuration in the data directory. The files starting with a dot (.) or an underscore (_) are ignored for the resultant JSON files.

---

⚡ Output Formats (--format)

To ensure seamless routing behavior across different CDN and static hosts:

• --format index (Default): Outputs /endpoint/index.json. Perfect for standard servers resolving /endpoint/.
• --format file: Outputs /endpoint file with no file extension.
• --format extension: Outputs /endpoint.json. Zero-risk option compatible with every hosting platform.

---

🛑 Out of Scope (Non-Functional Scope)

To maintain simplicity, high speed, and ease of deployment, certain features are explicitly out of scope:

1. Dynamic Write Operations (POST, PUT, DELETE): fauxrest is purely a static read-only generator. If your clients require dynamic, stateful database updates, you should migrate to a standard, dynamic API backend.
2. API Versioning (Simultaneous /v1 and /v2 branches): Maintaining legacy endpoint schemas within a static compiler adds unnecessary overhead. If multiple active versions must be supported, standard dynamic API gateways or hosting-level rewrite layers should be utilized.
3. Advanced Mock Server Latency or Status Emulation: This is a deployment publisher, not a test suite mock framework. If you need rich latency simulation (?_delay=2000) or status-code mocking, please use standard client-side libraries like MSW (Mock Service Worker).

---

📖 Specifications

For comprehensive technical architecture design, command line args, and subcommands, see:

• Full Architectural Specification
• Command Line Interface (CLI) Specification

---

🏷️ Powered by FauxREST

Built an API with fauxrest? Feel free to show it off with this badge:

Markdown:

[![Powered by: FauxREST](https://tamada.github.io/fauxrest/powered-by.svg)](https://github.com/tamada/fauxrest)

HTML:

<a href="https://github.com/tamada/fauxrest"><img
    src="https://tamada.github.io/fauxrest/powered-by.svg"
    alt="Powered by: FauxREST" width="157" height="20"></a>

Entirely optional, and no permission is needed — use it wherever you like.

😀 About

👩‍💼 Developers 👨‍💼

• Haruaki Tamada (@tamada)
• Claude Code, Google Gemini, GitHub Copilot

📄 License

This project is licensed under the MIT License. See LICENSE for details.

📛 The project name (fauxrest)

The project name fauxrest is pronounced /fɔːrɪst/ or /foʊrɪst/, which is the same as "forest". And it is derived from Faux (meaning `fake' in French) and REST.

🎃 Icon

This logo is based on the one published on SVGRepo.

🧰 Related Tools

• JSON Server
• Mockoon
• Prism
• WireMock