@paristech/json-server

Important

Enhanced JSON Server with nested routes support - A powerful REST API server for prototyping and development

A feature-rich JSON server that extends the original json-server with advanced nested routing capabilities, built by @paristech.

✨ Features

• Full REST API - All standard HTTP methods (GET, POST, PUT, PATCH, DELETE)
• Nested Routes - Access and modify nested resources within main resources
• Automatic ID Generation - Unique IDs for all resources
• Query Parameters - Filtering, sorting, pagination, and embedding
• Static File Serving - Serve static files alongside your API
• CORS Support - Built-in CORS handling
• TypeScript Support - Full type definitions included
• Real-time Updates - Automatic database persistence

🚀 Install

npm install @paristech/json-server

📖 Usage

Basic Setup

Create a db.json file:

{
  "surveys": [
    {
      "id": "123",
      "title": "Customer Satisfaction Survey",
      "design": {
        "theme": "modern",
        "colors": {
          "primary": "#007bff",
          "secondary": "#6c757d"
        }
      },
      "questions": [
        {
          "id": "q1",
          "text": "How satisfied are you?",
          "type": "rating"
        }
      ]
    }
  ]
}

Start the server:

npx @paristech/json-server db.json

Standard REST Routes

Based on your db.json, you get these standard routes:

GET    /surveys
GET    /surveys/:id
POST   /surveys
PUT    /surveys/:id
PATCH  /surveys/:id
DELETE /surveys/:id

🌟 Nested Routes (NEW!)

The enhanced feature that sets this server apart! Access and modify nested resources within your main resources.

Nested Resource Routes

GET    /surveys/123/design
POST   /surveys/123/design
PUT    /surveys/123/design
PATCH  /surveys/123/design
DELETE /surveys/123/design

GET    /surveys/123/questions
POST   /surveys/123/questions
PUT    /surveys/123/questions
PATCH  /surveys/123/questions
DELETE /surveys/123/questions

Specific Nested Item Routes

GET    /surveys/123/questions/q1
PUT    /surveys/123/questions/q1
PATCH  /surveys/123/questions/q1
DELETE /surveys/123/questions/q1

Examples

# Get survey 123's design
GET /surveys/123/design

# Update the design theme
PATCH /surveys/123/design
{"theme": "dark"}

# Add a new question
POST /surveys/123/questions
{"text": "New question?", "type": "text"}

# Update a specific question
PATCH /surveys/123/questions/q1
{"required": true}

# Replace entire design
PUT /surveys/123/design
{"theme": "colorful", "colors": {...}}

🔍 Query Parameters

Filtering

• → ==
• lt → <
• lte → <=
• gt → >
• gte → >=
• ne → !=

GET /surveys?title_contains=Customer
GET /surveys?created_at_gt=2024-01-01

Pagination

GET /surveys?_page=1&_per_page=25
GET /surveys?_start=10&_end=20
GET /surveys?_start=10&_limit=10

Sorting

GET /surveys?_sort=id,-created_at
GET /surveys?_sort=title,views

Embedding Related Data

GET /surveys?_embed=questions
GET /questions?_embed=survey

Nested Field Queries

GET /surveys?design.theme=modern
GET /surveys?questions.type=rating

🗑️ Delete Operations

# Delete a survey
DELETE /surveys/123

# Delete with dependent cleanup
DELETE /surveys/123?_dependent=questions

📁 Static File Serving

Create a ./public directory to serve static files alongside your API:

json-server -s ./static db.json
json-server -s ./static -s ./node_modules db.json

⚙️ CLI Options

npx @paristech/json-server --help

Common options:

• -p, --port - Set port (default: 3000)
• -H, --host - Set host (default: localhost)
• -s, --static - Serve static files from directory
• --delay - Add delay to responses (useful for testing)

🏗️ Project Structure

@paristech/json-server/
├── lib/                    # Compiled JavaScript
├── examples/              # Example databases
├── views/                 # HTML templates
├── package.json           # Dependencies and scripts
└── README.md             # This file

🧪 Examples

Check out the examples/ directory for sample databases and use cases:

# Run with example database
npx @paristech/json-server examples/nested-routes-example.json

🔧 Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

📚 API Reference

Main Resources

• GET /:resource - List all items
• GET /:resource/:id - Get specific item
• POST /:resource - Create new item
• PUT /:resource/:id - Replace item
• PATCH /:resource/:id - Update item
• DELETE /:resource/:id - Delete item

Nested Resources

• GET /:resource/:id/:nested - Get nested resource
• POST /:resource/:id/:nested - Add to nested resource
• PUT /:resource/:id/:nested - Replace nested resource
• PATCH /:resource/:id/:nested - Update nested resource
• DELETE /:resource/:id/:nested - Remove nested resource

Specific Nested Items

• GET /:resource/:id/:nested/:nestedId - Get specific nested item
• PUT /:resource/:id/:nested/:nestedId - Replace specific nested item
• PATCH /:resource/:id/:nested/:nestedId - Update specific nested item
• DELETE /:resource/:id/:nested/:nestedId - Remove specific nested item

🤝 Contributing

This project is maintained by @paristech. Contributions are welcome!

📄 License

This project is licensed under the terms specified in the LICENSE file.

🙏 Acknowledgments

Built on top of the excellent json-server by typicode, enhanced with nested routing capabilities.

---

Built with ❤️ by @paristech