JSON Server transforms frontend development by providing instant REST APIs from simple JSON files. Whether you’re building a React application, testing UI components, or demonstrating a proof-of-concept, JSON Server eliminates backend dependencies and accelerates your workflow.

This guide covers both available versions: the stable v0.17.4 (recommended for production-like testing) and v1.0.0-beta.3 (latest release with unreliable relational query features). Perfect for prototyping, testing, and learning, JSON Server requires no database configuration or server code. However, it’s strictly designed for development environments and should never be used in production.

This comprehensive guide walks you through installation, configuration, and best practices to help you choose the right version for your specific development needs.

What is JSON Server?

JSON Server is a Node.js tool that creates a full REST API from a simple JSON file. You provide a JSON file containing your data structure, and it automatically generates endpoints for GET, POST, PUT, PATCH, and DELETE operations. No database configuration, no server code, no complex routing setup.

The tool runs on your local machine or remote server and responds to HTTP requests just like a real API would. This eliminates backend dependencies during frontend development.

Purpose and Use-Cases

Developers use JSON Server for rapid prototyping. When building a React, Vue, or Angular application, you can start developing the frontend interface without waiting for the actual backend to be ready.

Testing UI components in isolation becomes straightforward. Create test data, simulate different scenarios, and verify your frontend logic works correctly before integrating with the real API. This approach supports parallel development and reduces blocking dependencies between teams.

The tool excels at creating demonstrations and proof-of-concepts. Mock up an entire application with realistic data interactions to show clients or stakeholders without investing weeks in backend development.

Version Notes and Compatibility

Critical: v1.0.0-beta.3 Has Known Issues

Confirmed Issues in Beta:

_embed and _expand are documented in the official README but users report they don’t work reliably (GitHub issue #1638 opened May 2024, still unresolved). Test thoroughly before relying on these features.
–routes flag not documented in v1 beta (GitHub issues #1512, #1601)

Use v0.17.4 for production-like work. Only use v1 beta if you don’t need relational queries, are testing new ID and sorting behaviors, or can switch versions if needed.

This guide covers both versions. Version 0.17.4 remains the production-ready choice with proven stability. Version 1.0.0-beta.3 remains in beta with documented features that don’t work reliably.

Fair Source License: Organizations with three or more users should sponsor the project to support sustainable development.

Version Comparison

Feature	v0.17.4 (Stable)	v1.0.0-beta.3
ID Type	Number or String	Always String
Pagination	_limit, _page + _limit, or _page + _per_page	_page + _per_page required
Sorting	_sort + _order	_sort=id,-views
Range	_start, _end, _limit	_start, _end, _limit
Node.js	14+	18.3+
Routes	Working (--routes)	Not documented
_embed	Working	Documented but unreliable
_expand	Working	Documented but unreliable
Stability	Production-ready	Beta (test features)
Recommended	Yes (default)	Testing only

Note: v0.17.4 supports multiple pagination approaches: use _limit alone, _page with _limit, or _page with _per_page. v1 requires both _page and _per_page together.

Decision Guide

Choose the right version for your needs:

Your Situation	Recommended Version
Need routes or _embed	v0.17.4
Just testing basic CRUD	v1 beta works
Production-like testing	v0.17.4
Teaching/learning basics	Either version

Quick Start – Choose Your Version First

Option A: Stable v0.17.4 (Recommended)

Install the stable version that includes working routes and embed functionality:

				
					npm install -g json-server@0.17.4

Create your data file. Numeric IDs work perfectly in v0.17.4:

				
					echo '{"posts":[{"id":1,"title":"Hello World"}]}' > db.json

Start the server using the official simple form:

				
					npx json-server db.json

Or with watch flag for automatic reloading (recommended for development):

				
					npx json-server --watch db.json

Test that relational queries work correctly in this version:

				
					curl "http://localhost:3000/posts?_embed=comments"

Option B: v1.0.0-beta.3 (Testing Only)

Run the beta version without permanent installation:

				
					npx json-server@1.0.0-beta.3 db.json

Create data file with string IDs, which are required in v1 beta:

				
					echo '{"posts":[{"id":"1","title":"Hello"}]}' > db.json

Start the server. Keep in mind that relational query features are unreliable in this beta version:

				
					npx json-server@1.0.0-beta.3 --watch db.json

Warning: Routes, embed, and expand features have reliability issues in v1.0.0-beta.3. Use v0.17.4 if you need these features.

Installation Prerequisites

For v1.0.0-beta.3: Node.js 18.3 or higher is required. For v0.17.4: Node.js 14 or higher is required.

Recommended versions include Node.js 20.x or Node.js 22.x LTS. Node.js 22.x LTS (recommended for new projects) offers the best balance of features and long-term support for new projects.

Long-term support versions provide security patches and stability. npm comes bundled with Node.js and serves as the package manager for installing JSON Server.

Setting Up Node.js on Debian 12

Whether you’re setting up locally or deploying for team collaboration, start by updating your system packages to ensure everything is current:

				
					apt update && apt upgrade -y

Verify the Installation

Check if Docker and the Compose plugin are working:

				
					Install Node.js and npm from the official NodeSource repository to get the latest LTS version with automatic updates:

You should see the current version numbers for both. Run a quick test container to confirm everything’s healthy:

				
					curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt install -y nodejs

For other Linux distributions or installation methods, visit the NodeSource repository.

Verify the installation by checking the versions:

				
					node -v
npm -v

Installing JSON Server

Option 1: Global Installation

Global installation provides persistent access across all projects.

For stable v0.17.4 (recommended for most users):

				
					npm install -g json-server@0.17.4

For testing v1 beta features:

				
					npm install -g json-server@1.0.0-beta.3

Option 2: One-Time Use with npx

Run without permanent installation, ideal for occasional use or evaluation:

				
					npx json-server@0.17.4 db.json

Verify Installation

Check that JSON Server is available on your system:

				
					json-server --version

Creating Your First Mock API

Create a JSON file with your mock data structure. This file acts as your database and defines what resources your API will serve:

				
					{
  "posts": [
    {
      "id": 1,
      "title": "Getting Started with JSON Server",
      "author": "John Doe",
      "views": 150
    }
  ],
  "comments": [
    {
      "id": 1,
      "text": "Great article",
      "postId": 1
    }
  ]
}

Start JSON Server with the simple form:

				
					npx json-server db.json

Or with the watch flag for automatic reloading when you modify db.json:

				
					npx json-server --watch db.json

Your API now runs at http://localhost:3000 with all available routes displayed.

Understanding CRUD Operations

JSON Server automatically creates endpoints for each resource. Retrieve all posts using a GET request:

				
					curl http://localhost:3000/posts

Get a specific post by including its ID in the URL:

				
					curl http://localhost:3000/posts/1

Create a new post by sending a POST request with JSON data:

				
					curl -X POST http://localhost:3000/posts \
  -H "Content-Type: application/json" \
  -d '{"title":"New Post","author":"Mike","views":0}'

Update a post completely using PUT or partially using PATCH:

				
					curl -X PATCH http://localhost:3000/posts/1 \
  -H "Content-Type: application/json" \
  -d '{"views":250}'

Delete a post using the DELETE method:

				
					curl -X DELETE http://localhost:3000/posts/1

ID Handling Differences

In version 0.17.4, IDs can be numbers or strings. The server accepts both formats and maintains your choice.

In version 1.0.0-beta.3, IDs are always strings. The server auto-generates string IDs when you omit them during record creation. Even if you provide numeric IDs, they convert to strings.

Example of auto-generated string IDs in v1 beta:

				
					curl -X POST http://localhost:3000/posts \
  -H "Content-Type: application/json" \
  -d '{"title":"Auto ID Post","views":0}'

This returns a response with string ID:

				
					{"id":"2","title":"Auto ID Post","views":0}

Working with Query Parameters

Sort results by any field using the _sort parameter. In v0.17.4, use _sort with _order:

				
					curl "http://localhost:3000/posts?_sort=views&_order=desc"

In v1.0.0-beta.3, you can use comma-separated fields with minus prefix for descending order:

				
					curl "http://localhost:3000/posts?_sort=id,-views"

Or single field with minus sign for descending order:

				
					curl "http://localhost:3000/posts?_sort=-views"

For ascending order:

				
					curl "http://localhost:3000/posts?_sort=views"

Search across all string fields using the q parameter. This performs case-insensitive searches and matches partial strings:

				
					curl "http://localhost:3000/posts?q=JSON"

v0.17.4 offers flexible pagination options:

				
					# Option 1: Limit only (first 10 records)
curl "http://localhost:3000/posts?_limit=10"

# Option 2: Page with limit
curl "http://localhost:3000/posts?_page=1&_limit=10"

# Option 3: Page with per_page
curl "http://localhost:3000/posts?_page=1&_per_page=10"

All three approaches work in v0.17.4, giving you flexibility in how you structure pagination requests.

Paginate results in v1 beta using _per_page:

				
					curl "http://localhost:3000/posts?_page=1&_per_page=10"

Filter results using comparison operators: _gt (greater than), _gte (greater than or equal), _lt (less than), _lte (less than or equal), and _ne (not equal):

				
					curl "http://localhost:3000/posts?views_gte=100&views_lte=200"

These pagination methods correspond to the version differences outlined in the comparison table above. Choose the approach that matches your version.

Range Selection

Use range parameters to slice results. These work in both v0.17.4 and v1.0.0-beta.3.

Get records 10 through 19:

				
					curl "http://localhost:3000/posts?_start=10&_end=20"

Get 10 records starting from index 10:

				
					curl "http://localhost:3000/posts?_start=10&_limit=10"

Working with Related Data

Version 0.17.4 (Reliable)

Relational queries work consistently in v0.17.4. Embed comments in posts:

				
					curl "http://localhost:3000/posts?_embed=comments"

Expand post in comment:

				
					curl "http://localhost:3000/comments?_expand=post"

Version 1.0.0-beta.3 Workarounds

The official v1 documentation shows _embed and _expand syntax, but multiple users report these features don’t work reliably (GitHub issue #1638, opened May 2024, still unresolved).

For v1 beta users who need relational data, use the workaround implementations described below.

Official syntax that may not work:

				
					curl "http://localhost:3000/posts?_embed=comments"

Recommended workarounds:

Workaround 1: Separate Requests

Fetch the post:

				
					curl http://localhost:3000/posts/1

Fetch related comments:

				
					curl "http://localhost:3000/comments?postId=1"

Combine in your application code:

				
					const post = await fetch('/posts/1').then(r => r.json())
const comments = await fetch(`/comments?postId=${post.id}`).then(r => r.json())
post.comments = comments

Workaround 2: Custom Middleware

Create custom middleware to manually join data. Save this as embed-middleware.js:

				
					// embed-middleware.js
const fs = require('fs')

module.exports = function(req, res, next) {
  if (req.query._embed) {
    const db = JSON.parse(fs.readFileSync('db.json', 'utf8'))
    const resource = req.path.split('/')[1]
    const embedResource = req.query._embed
    
    let data = db[resource]
    if (Array.isArray(data)) {
      data.forEach(item => {
        item[embedResource] = db[embedResource].filter(
          sub => sub[`${resource.slice(0, -1)}Id`] === item.id
        )
      })
    }
    return res.json(data)
  }
  next()
}

Load the middleware when starting your server:

				
					json-server db.json --middlewares embed-middleware.js

Setting Up Custom Routes

Version 0.17.4 (Working)

Custom routes work perfectly in v0.17.4 using the –routes flag. Create a routes configuration file:

				
					{
  "/api/*": "/$1",
  "/blog/:resource/:id/comments": "/:resource/:id/comments"
}

Start JSON Server with the routes file:

				
					json-server db.json --routes routes.json

Version 1.0.0-beta.3 (Not Documented)

The –routes flag is not documented in v1.0.0-beta.3 (GitHub issues #1512, #1601). Use custom middleware as a workaround.

Save this as routes-middleware.js:

				
					// routes-middleware.js
module.exports = function(req, res, next) {
  if (req.url.startsWith('/api/')) {
    req.url = req.url.replace('/api/', '/')
  }
  next()
}

Load the routes middleware when starting your server:

				
					json-server db.json --middlewares routes-middleware.js

Implementing Middleware

Create middleware files to add custom logic. Middleware functions run before JSON Server processes requests.

Save this as middleware.js:

				
					// middleware.js
module.exports = function(req, res, next) {
  console.log(`${req.method} ${req.url}`)
  res.header('X-Custom-Header', 'Value')
  next()
}

Load middleware when starting the server:

				
					json-server db.json --middlewares middleware.js

Serving Static Files

JSON Server serves static files alongside your API. Create a public directory for static content:

				
					mkdir public
echo '<h1>API Documentation</h1>' > public/index.html

Start the server with static file serving enabled:

				
					json-server db.json --static ./public

Performance Considerations

JSON Server loads the entire database into memory. Small datasets under 1MB provide excellent performance. Medium datasets between 1MB and 10MB offer good performance. Large datasets exceeding 10MB show noticeable slowdown.

For datasets with more than 10,000 records, use pagination for all requests, implement data filtering at the client level, or switch to a real database for testing.

For teams working with large datasets, hosting JSON Server on a remote development server ensures consistent performance across all developers. This eliminates environment-specific issues and provides a shared testing environment. If your team needs this setup, consider deploying to a VPS with appropriate access controls.

Security Considerations

JSON Server is designed for development environments only. Never expose it to the public internet without additional security measures. Use firewall rules to restrict access.

Allow connections only from specific IP addresses:

				
					sudo ufw allow from 192.168.1.100 to any port 3000

The tool does not support HTTPS by default. For encrypted connections, place it behind nginx.

Example nginx configuration:

				
					server {
    listen 443 ssl;
    server_name api.example.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
    }
}

Common Pitfalls to Avoid

Version 1.0.0-beta.3 Specific:

Using –routes flag: Not documented in v1 beta. Use v0.17.4 or custom middleware.

Expecting _embed to work reliably: Documented but unreliable (GitHub issue #1638). Use v0.17.4 or make separate requests.

Using numeric IDs: IDs must be strings like “1” not numbers in v1 beta.

General Issues:

Forgetting –watch flag: Changes to db.json will not reflect without server restart.

Exposing to internet without security: JSON Server has no authentication. Use firewall protection.

Large datasets exceeding 10MB: Performance degrades significantly. Use pagination and consider real databases.

Alternative Tools

Mirage JS runs entirely in the browser and intercepts network requests at the client level, ideal for frontend-only development.

Mockoon offers a desktop application with a graphical interface for developers who prefer visual tools.

WireMock is written in Java and provides advanced stubbing for simulating complex API behaviors.

Postman Mock Server integrates with the Postman ecosystem for teams already using Postman for API testing.

When to Use JSON Server

Choose JSON Server for rapid prototyping when you need quick mock APIs for JavaScript projects. Perfect for hackathons, prototypes, and proof-of-concepts where speed matters. The tool works well for small to medium-sized applications during development. Migrate to proper backends with database persistence before production launch. JSON Server excels for teaching and learning. Students can focus on frontend concepts without backend complexity.

Conclusion

JSON Server excels at rapid prototyping when you need quick mock APIs. Choose your version carefully: v0.17.4 offers reliability with all features working correctly, while v1.0.0-beta.3 should only be used if you can work around unreliable relational query features.

For most projects, v0.17.4 remains the safest choice until v1 stabilizes. Start with the Quick Start commands above, test your specific use case, and plan migration to production backends before launch. Remember this is strictly a development tool designed to accelerate prototyping, not replace production infrastructure. The tool’s simplicity makes it invaluable during early development stages, but proper backend systems with authentication, data persistence, and scalability should be implemented for production deployments.

JSON-Server Installation: Setting Up Mock APIs