JSON-X Server

Advanced JSON REST API server with modern admin dashboard for rapid prototyping and development.

✨ Features

🎯 Core Functionality

• JSON File Database: Zero-config file-based storage
• RESTful CRUD: Full Create, Read, Update, Delete operations
• Schema Validation: Automatic and custom field validation
• Data Relationships: One-to-one, one-to-many, many-to-many
• Advanced Querying: Filtering, sorting, pagination, population

🚀 Modern Admin Dashboard

• Real-time Updates: WebSocket-powered live data sync
• Responsive Design: Modern, professional interface
• Collections Management: Visual data browser and editor
• Schema Editor: Field-level validation rules
• Request Monitoring: Live request logging and analytics
• Password Protection: Session-based authentication

🔒 Security & Performance

• CORS Management: Configurable cross-origin policies
• Request Limits: Body size and rate limiting
• IP-based Rate Limiting: Prevent DoS attacks
• Admin Protection: Secure dashboard access
• Session Management: 24-hour token-based auth

🛠️ Developer Tools

• Automatic Backups: Scheduled data protection
• Export Formats: JSON, CSV, XML support
• File Upload Simulation: Multipart form handling
• Production Generator: Create optimized deployments

📦 Installation

npm install -g jsonxapi

🚀 Quick Start

Basic Usage

# Start server on default port 4000
jsonxapi

# Custom port and database file
jsonxapi --port 3000 --db mydata.json

# With admin password protection
jsonxapi --port 4000 --password secretpass

API Access

# Create a record
curl -X POST http://localhost:4000/users \
  -H "Content-Type: application/json" \
  -d '{"name": "John Doe", "email": "[email protected]"}'

# Get all records
curl http://localhost:4000/users

# Get specific record
curl http://localhost:4000/users/123

# Update record
curl -X PATCH http://localhost:4000/users/123 \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Doe"}'

# Delete record
curl -X DELETE http://localhost:4000/users/123

🎛️ Admin Dashboard

Access the modern admin interface at http://localhost:4000/_admin

Dashboard Features

📊 Overview

• Live server statistics
• Collection summaries
• Real-time request monitoring
• WebSocket connection status

📁 Collections Management

• Browse and edit data visually
• Add/update/delete records
• Schema validation feedback
• Export collections in multiple formats

🔧 Schema Editor

• Define field types and validation rules
• Set required fields and constraints
• Manage relationships between collections
• Live schema updates

📝 Request Monitor

• Live request logging
• HTTP method and endpoint tracking
• Response time analytics
• Error monitoring

⚙️ Configuration

• CORS settings management
• Request size and rate limits
• Backup and restore operations
• WebSocket settings

📖 API Reference

Collections Endpoints

| Method | Endpoint | Description | | -------- | -------------------- | ------------------- | | GET | /{collection} | Get all records | | GET | /{collection}/{id} | Get specific record | | POST | /{collection} | Create new record | | PATCH | /{collection}/{id} | Update record | | DELETE | /{collection}/{id} | Delete record |

Query Parameters

Filtering

# Filter by field value
GET /users?name=John

# Multiple filters
GET /users?status=active&role=admin

# Range queries
GET /products?price_gte=10&price_lte=100

Sorting

# Sort ascending
GET /users?_sort=name

# Sort descending
GET /users?_sort=name&_order=desc

# Multiple fields
GET /users?_sort=name,email&_order=asc,desc

Pagination

# Limit results
GET /users?_limit=10

# Skip records
GET /users?_start=20&_limit=10

# Page-based
GET /users?_page=2&_limit=10

Population

# Populate all relationships
GET /posts?_populate=true

# Populate specific fields
GET /posts?_populate=author,comments

Export Formats

# Export as CSV
GET /users?_format=csv

# Export as XML
GET /users?_format=xml

# Download file
GET /users?_format=csv&_download=true

🔧 Configuration

Command Line Options

| Option | Description | Default | | ------------ | ------------------------ | --------- | | --port | Server port | 4000 | | --db | Database file path | db.json | | --password | Admin dashboard password | None |

Environment Variables

# Alternative configuration
export JX_PORT=3000
export JX_DB_FILE=data.json
export JX_ADMIN_PASSWORD=mypassword

📋 Schema Validation

Supported Field Types

• string - Text data
• number - Numeric values
• boolean - True/false
• array - Lists of values
• object - Nested objects

Validation Rules

{
  "_schemas": {
    "users": {
      "name": {
        "type": "string",
        "required": true,
        "minLength": 2,
        "maxLength": 50
      },
      "email": {
        "type": "string",
        "required": true,
        "pattern": "^[^@]+@[^@]+\\.[^@]+$"
      },
      "age": {
        "type": "number",
        "min": 0,
        "max": 150
      },
      "active": {
        "type": "boolean",
        "default": true
      }
    }
  }
}

🔗 Relationships

Defining Relationships

{
  "_relationships": {
    "posts": {
      "author": {
        "type": "belongsTo",
        "collection": "users",
        "foreignKey": "authorId"
      },
      "comments": {
        "type": "hasMany",
        "collection": "comments",
        "foreignKey": "postId"
      }
    }
  }
}

Relationship Types

• belongsTo: One-to-one, record belongs to another
• hasMany: One-to-many, record has multiple related records
• hasOne: One-to-one, record has one related record
• belongsToMany: Many-to-many through junction table

🛡️ Security

CORS Configuration

# Configure via admin dashboard or API
POST /_admin_cors
{
  "enabled": true,
  "origin": ["http://localhost:3000", "https://myapp.com"],
  "methods": ["GET", "POST", "PATCH", "DELETE"],
  "allowCredentials": true
}

Request Limits

# Set via admin dashboard
POST /_admin_limits
{
  "enabled": true,
  "maxBodySize": 1048576,
  "maxFileSize": 10485760,
  "maxRequestsPerMinute": 1200
}

💾 Backup & Restore

Automatic Backups

• Daily automated backups
• Configurable retention period
• Backup management via admin dashboard

Manual Operations

# Create backup via API
POST /_admin_backup
{
  "name": "before-migration"
}

# Restore from backup
POST /_admin_restore
{
  "backupName": "backup-2024-01-15"
}

🚢 Production Deployment

Generate Production Server

Use the admin dashboard to generate an optimized production version:

1. Navigate to "Server Generator"
2. Configure production settings
3. Download generated server package
4. Deploy to your hosting platform

Production Considerations

• Set strong admin passwords
• Configure appropriate CORS policies
• Enable request limiting
• Set up regular backups
• Monitor request logs

🔌 WebSocket Support

Real-time Updates

const ws = new WebSocket("ws://localhost:4000/ws");

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log("Real-time update:", data);
  // Handle collection changes
};

// Subscribe to specific collection
ws.send(
  JSON.stringify({
    type: "subscribe",
    collection: "users",
  })
);

📝 Examples

E-commerce API

# Products
POST /products
{
  "name": "Laptop",
  "price": 999.99,
  "category": "electronics",
  "stock": 50
}

# Orders with relationships
POST /orders
{
  "customerId": 123,
  "items": [
    {"productId": 456, "quantity": 2}
  ],
  "total": 1999.98
}

# Query with population
GET /orders?_populate=customer,items.product

Blog API

# Posts with validation
POST /posts
{
  "title": "Getting Started with JSON-X Server",
  "content": "This is a comprehensive guide...",
  "authorId": 1,
  "published": true,
  "tags": ["tutorial", "api", "nodejs"]
}

# Comments relationship
POST /comments
{
  "postId": 1,
  "author": "John Doe",
  "content": "Great article!",
  "email": "[email protected]"
}

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

git clone https://github.com/Aladdin16659/jsonx-server
cd jsonx-server
npm install
npm run dev

📄 License

MIT © Aladdin Sidahmed

🆘 Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📧 Email Support

Made with ❤️ for developers who need fast, reliable JSON APIs