rs-mock-server 🦀

A simple, zero-configuration mock server built in Rust. Spin up a realistic REST API for local development or testing just by creating folders and files.

It works by scanning a directory and mapping its structure directly to API routes, with clever filename conventions for handling HTTP methods, dynamic parameters, and static assets.

Features

• 🚀 File-System Routing: Your folder structure defines your API routes. No config files needed.
• 🧩 Dynamic Path Generation: Create routes with parameters ({id}), specific values ({admin}), and even numeric ranges ({1-10}) right from the filename.
• ⚙️ Full HTTP Method Support: Define GET, POST, PUT, DELETE, PATCH, and OPTIONS endpoints.
• 🔗 In-Memory REST API: Create fully functional CRUD APIs with automatic ID generation and data persistence during runtime using special rest.json files.
• 📤 File Upload & Download: Create upload endpoints with automatic file handling and download capabilities using special {upload} folders.
• 🖼️ Static File Serving: Automatically serves any file (like images, CSS, or JS) with its correct Content-Type if the filename doesn't match a method pattern.
• 🌐 Public Directory Serving: Serve a directory of static files (e.g., a frontend build) from a root public folder, or map a folder like public-assets to a custom /assets route.
• 🔧 Configurable: Easily change the port and mock directory via command-line arguments.
• ⚡ Lightweight & Fast: Built with Rust for minimal resource usage and maximum performance.

How It Works

The server recursively scans a root directory (defaults to ./mocks) and translates the file and folder paths into API endpoints.

Folder Structure → URL Path

The path of each folder becomes the base URL for the routes within it.

• A folder at ./mocks/api/users creates the base route /api/users.
• A nested folder at ./mocks/api/users/profiles creates the base route /api/users/profiles.

Filename Conventions → Endpoints

The name of a file determines the HTTP method and the final URL segment. The content of the file is served as the response body.

The following table shows how different filename patterns are mapped to routes, assuming they are inside a ./mocks/api/users directory:

In-Memory REST API

For rapid prototyping and testing, you can create fully functional CRUD APIs using special rest.json files. When the server detects a file named rest.json or rest{params}.json, it automatically:

1. Loads initial data from the JSON array in the file
2. Creates a complete REST API with all CRUD operations
3. Maintains data in memory during the server's lifetime
4. Handles ID generation automatically for new items

REST File Naming Convention

The {params} in the filename configures the ID field behavior:

Generated Endpoints

For a rest.json file in ./mocks/api/products/, the following endpoints are automatically created:

Initial Data Format

The JSON file should contain an array of objects, where each object represents an item with the configured ID field:

[
    {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "name": "Wireless Headphones",
        "price": 199.99,
        "category": "Electronics"
    },
    {
        "id": "550e8400-e29b-41d4-a716-446655440002",
        "name": "Coffee Mug",
        "price": 15.99,
        "category": "Kitchen"
    }
]

For integer IDs using rest{_id:int}.json:

[
    {
        "_id": 1,
        "name": "Product One",
        "description": "First product"
    },
    {
        "_id": 2,
        "name": "Product Two",
        "description": "Second product"
    }
]

Special "Public" Folder for Static Serving

To serve a directory of static assets (like a frontend app), you can use a specially named public folder in your mock directory root.

• public folder: If you create a folder named public, all its contents will be served from the /public route.

  • ./mocks/public/home.html → GET /public/home.html

• public-<alias> folder: You can customize the URL path by adding a dash. A folder named public-static will serve its files from the /static route.

  • ./mocks/public-static/style.css → GET /static/style.css

Special "{upload}" Folder for File Handling

For file upload and download functionality, you can create a specially named {upload} folder. When detected, the server automatically creates endpoints for uploading and downloading files.

Basic Upload Folder

• {upload} folder: Creates upload and download endpoints at /upload.

  • POST /upload - Upload files (multipart/form-data)
  • GET /upload/{filename} - Download files by name

Upload Folder Configuration

The {upload} folder supports additional configuration through special naming patterns:

Examples

• Basic: ./mocks/{upload}/ creates POST /upload and GET /upload/{filename}
• Temporary: ./mocks/{upload}{temp}/ - same endpoints, but files are cleaned up when server stops
• Custom Route: ./mocks/{upload}-files/ creates POST /files and GET /files/{filename}
• Combined: ./mocks/{upload}{temp}-upfiles/ creates POST /upfiles and GET /upfiles/{filename} with automatic cleanup

All uploaded files are saved in the detected folder with their original filenames, and downloads include proper Content-Type and Content-Disposition headers.

Installation

With Cargo

You can install it directly:

cargo install rs-mock-server

From Source

Alternatively, you can clone the repository and build it yourself:

# Clone the repository
git clone https://github.com/lvendrame/rs-mock-server.git

# Navigate into the project directory
cd rs-mock-server

# Build the project for release
cargo build --release

# The executable will be at ./target/release/rs-mock-server
./target/release/rs-mock-server --help

Usage

You can run the server using the rs-mock-server executable.

To start the server with default settings: (This will use the ./mocks folder and run on port 4520)

rs-mock-server

To specify a custom port and mock directory:

rs-mock-server --port 8080 --folder ./my-api-mocks

Command-Line Options

Usage: rs-mock-server [OPTIONS]

Options:
  -p, --port <PORT>      Port to run the server on [default: 4520]
  -f, --folder <FOLDER>  Directory to load mock files from [default: mocks]
  -h, --help             Print help
  -V, --version          Print version

Example Walkthrough

Imagine you have the following directory structure:

mocks/
├── api/
│   ├── users/
│   │   ├── get.json         # Contains a JSON array of all users
│   │   ├── post.json        # Contains a success message for user creation
│   │   └── get{id}.json    # Contains a single user object template
│   ├── products/
│   │   ├── rest{_id:int}.json # In-memory REST API with integer IDs
│   │   ├── get{1-3}.json   # Contains a product template for IDs 1, 2, 3
│   │   └── get{special}.json# Contains a specific "special" product
│   ├── companies/
│   │   └── rest.json        # In-memory REST API with UUID IDs
│   └── status.txt           # Contains the plain text "API is running"
├── assets/
│   └── logo.svg             # An SVG image file
├── {upload}/                # Upload folder for file handling
├── {upload}{temp}-docs/     # Temporary upload folder with custom route
└── public-static/
    ├── image.jpg            # An JPG image file
    └── css/
        └── style.css        # A stylesheet

Running rs-mock-server in the same directory will create the following endpoints:

Note:

• The REST API endpoints provide full CRUD functionality with automatic ID generation, data persistence during runtime, and initial data loading from the JSON files.
• Upload endpoints handle multipart/form-data file uploads and preserve original filenames.
• Download endpoints serve files with proper Content-Type detection and Content-Disposition headers.
• Temporary upload folders ({temp}) automatically clean up all files when the server stops.
• You can interact with all endpoints using any HTTP client, and data will persist until the server is restarted.