servson

Complete REST Mock API in seconds using just a single JSON file. Create mocks for your front-end in seconds.

How to use

Run the init command to generate the default configuration file mock.json:

npx servson init

Start the Server

Pass the configuration file you want to use to servson:

npx servson mock.json

The REST Mock API server will start on the port defined in settings.port.

Configuration file (mock.json)

The configuration file defines your mock data models.

{
    "$schema": "https://unpkg.com/servson@latest/static/schema.json",
    "settings": {
        "host": "localhost",
        "port": 3000,
        "identity": {
            "type": "number",
            "field": "id"
        },
        "timestamps": {
            "createdAt": true,
            "updatedAt": true
        },
        "pagination": {
            "limit": 10
        },
        "responses": {
            "get": { "status": 200 },
            "post": { "status": 201 },
            "put": { "status": 200 },
            "delete": { "status": 204 },
            "errors": {
                "modelNotFound": {
                    "status": 404,
                    "message": "Model '{{model}}' not found"
                },
                "notFound": {
                    "status": 404,
                    "message": "Item not found"
                },
                "duplicate": {
                    "status": 400,
                    "message": "Item already exists"
                }
            }
        }
    },
    "models": [
        {
            "name": "user",
            "data": [
                {
                    "name": "John Doe",
                    "email": "[email protected]"
                }
            ]
        }
    ]
}

REST Endpoints

For each model defined in models, servson automatically exposes the following RESTful routes:

GET          /              Lists status and available routes   200
GET          /:model        Lists all records                   200
GET          /:model/:id    Finds a record by ID                200 / 404
POST         /:model        Creates a new record                201 / 400
PUT          /:model/:id    Updates a record by ID              200 / 404
DELETE       /:model/:id    Removes a record by ID              204 / 404

Query Parameters (Pagination & Sorting)

The GET /:model endpoint supports pagination and sorting via query parameters:

GET /user?page=2               # Page number to fetch (default: 1)
GET /user?limit=5              # Max items returned in data (default: 10 or settings.pagination.limit)
GET /user?sort=name            # Sort by field ascending
GET /user?sort=-views          # Sort by field descending (prefix with -)
GET /user?page=2&limit=5&sort=name # Combine page, limit, and sorting

Paginated Response Format

{
    "first": 1,
    "prev": null,
    "next": 2,
    "last": 5,
    "pages": 5,
    "items": 25,
    "data": [
        {
            "id": 1,
            "name": "John Doe",
            "email": "[email protected]"
        }
    ]
}

CLI Commands

Usage: servson [options] [command] [config]

Mock REST API via JSON file

Arguments:
  config               JSON configuration file

Options:
  -v, --version        Display version
  -c, --config <path>  Configuration file path
  -h, --help           Display help

Commands:
  init [options]       Generate mock.json file

init command options

servson init [options]

• -f, --force: Overwrite without asking.

License

MIT