json-rest-api 0.1.1 → 1.0.0

package/docs/GUIDES.md

@@ -0,0 +1,1792 @@
+# JSON REST API - Complete Guide
+
+Welcome to the JSON REST APIs! This guide will take you from zero to hero, one step at a time. We'll build a complete task management system to learn every feature of this library.
+
+## Table of Contents
+
+1. [Quick Start Guide](#quick-start-guide)
+2. [Core Concepts Tutorial](#core-concepts-tutorial)
+3. [Plugin Tutorials](#plugin-tutorials)
+4. [Advanced Features](#advanced-features)
+
+---
+
+# Quick Start Guide
+
+Let's build a simple task management API in 10 minutes!
+
+## Step 1: Installation
+
+```bash
+npm init -y
+npm install express mysql2
+npm install jsonrestapi
+```
+
+## Step 2: Create Your First API
+
+Create a file called `server.js`:
+
+```javascript
+import express from 'express';
+import { createApi, Schema } from 'jsonrestapi';
+
+// Create Express app
+const app = express();
+
+// Create your API with a name and version
+const api = createApi({
+  name: 'taskmanager',
+  version: '1.0.0',
+  storage: 'memory',  // We'll use memory for now
+  http: { basePath: '/api' }  // This automatically adds HTTPPlugin!
+});
+
+// Define a schema for tasks
+const taskSchema = new Schema({
+  id: { type: 'id' },
+  title: { type: 'string', required: true, min: 1, max: 200 },
+  description: { type: 'string', max: 1000 },
+  completed: { type: 'boolean', default: false },
+  priority: { type: 'string', default: 'medium' },
+  createdAt: { type: 'timestamp', default: () => Date.now() }
+});
+
+// Register the schema
+api.addResource('tasks', taskSchema);
+
+// Mount the API on Express
+api.mount(app);
+
+// Start the server
+app.listen(3000, () => {
+  console.log('🚀 API running at http://localhost:3000');
+  console.log('📝 Try: GET http://localhost:3000/api/1.0.0/tasks');
+});
+```
+
+### 💡 Behind the Scenes: What createApi Does
+
+The `createApi()` helper is a convenience function that automatically configures plugins for you. Here's what the above code would look like WITHOUT the helper:
+
+```javascript
+import express from 'express';
+import { 
+  Api, 
+  Schema, 
+  ValidationPlugin, 
+  MemoryPlugin, 
+  HTTPPlugin 
+} from 'jsonrestapi';
+
+const app = express();
+
+// Manual approach - full control over plugins
+const api = new Api({
+  name: 'taskmanager',
+  version: '1.0.0'
+});
+
+// Manually add each plugin
+api.use(ValidationPlugin);  // Always needed for schemas
+api.use(MemoryPlugin);      // For in-memory storage
+api.use(HTTPPlugin, { basePath: '/api' });  // For REST endpoints
+
+// Rest is the same...
+```
+
+The `createApi()` helper automatically adds plugins based on your options:
+- `storage: 'memory'` → adds MemoryPlugin
+- `storage: 'mysql'` → adds MySQLPlugin
+- `http: { ... }` → adds HTTPPlugin
+- `positioning: { ... }` → adds PositioningPlugin
+- `versioning: { ... }` → adds VersioningPlugin
+- ValidationPlugin is always added (unless `validation: false`)
+
+Use `createApi()` for quick setup, or use `Api` directly when you need full control!
+
+## Step 3: Test Your API
+
+Run your server:
+```bash
+node server.js
+```
+
+Now you can:
+
+```bash
+# Create a task
+curl -X POST http://localhost:3000/api/1.0.0/tasks \
+  -H "Content-Type: application/json" \
+  -d '{"data": {"type": "tasks", "attributes": {"title": "Learn JSON REST API"}}}'
+
+# List all tasks
+curl http://localhost:3000/api/1.0.0/tasks
+
+# Get a specific task
+curl http://localhost:3000/api/1.0.0/tasks/1
+
+# Update a task
+curl -X PATCH http://localhost:3000/api/1.0.0/tasks/1 \
+  -H "Content-Type: application/json" \
+  -d '{"data": {"attributes": {"completed": true}}}'
+
+# Delete a task
+curl -X DELETE http://localhost:3000/api/1.0.0/tasks/1
+```
+
+## Step 4: Add MySQL Storage
+
+Let's make it persistent! Update your `server.js`:
+
+```javascript
+import { createApi, Schema, MySQLPlugin } from 'jsonrestapi';
+
+// Create API with MySQL
+const api = createApi({
+  name: 'taskmanager',
+  version: '1.0.0',
+  storage: 'mysql',
+  mysql: {
+    connection: {
+      host: 'localhost',
+      user: 'root',
+      password: 'password',
+      database: 'taskmanager'
+    }
+  },
+  http: { basePath: '/api' }
+});
+
+// Same schema as before
+const taskSchema = new Schema({
+  id: { type: 'id' },
+  title: { type: 'string', required: true, min: 1, max: 200 },
+  description: { type: 'string', max: 1000 },
+  completed: { type: 'boolean', default: false },
+  priority: { type: 'string', default: 'medium' },
+  createdAt: { type: 'timestamp', default: () => Date.now() }
+});
+
+api.addResource('tasks', taskSchema);
+
+// Magic! Sync the database automatically
+await api.syncSchema(taskSchema, 'tasks');
+
+api.mount(app);
+```
+
+## Step 5: Add Users with Relationships
+
+Let's add a users table:
+
+```javascript
+// User schema
+const userSchema = new Schema({
+  id: { type: 'id' },
+  username: { type: 'string', required: true, min: 3, max: 50 },
+  email: { type: 'string', required: true, lowercase: true },
+  passwordHash: { type: 'string', required: true },
+  createdAt: { type: 'timestamp', default: () => Date.now() }
+});
+
+// Update task schema to include user
+const taskSchema = new Schema({
+  id: { type: 'id' },
+  userId: { type: 'id', required: true },  // Link to user
+  title: { type: 'string', required: true, min: 1, max: 200 },
+  description: { type: 'string', max: 1000 },
+  completed: { type: 'boolean', default: false },
+  priority: { type: 'string', default: 'medium' },
+  createdAt: { type: 'timestamp', default: () => Date.now() }
+});
+
+// Register both schemas
+api.addResource('users', userSchema);
+api.addResource('tasks', taskSchema);
+
+// Sync both tables
+await api.syncSchema(userSchema, 'users');
+await api.syncSchema(taskSchema, 'tasks');
+```
+
+Congratulations! You now have a working API with two related tables! 🎉
+
+---
+
+# Core Concepts Tutorial
+
+## Understanding Schemas
+
+Schemas are the heart of your API. They define what your data looks like and how it's validated.
+
+### Basic Types
+
+```javascript
+const productSchema = new Schema({
+  // Numeric types
+  id: { type: 'id' },                    // Auto-incrementing ID
+  price: { type: 'number', min: 0 },     // Positive numbers only
+  stock: { type: 'number', default: 0 }, // Default value
+  
+  // String types
+  name: { type: 'string', required: true },
+  sku: { type: 'string', uppercase: true },  // Auto-uppercase
+  description: { type: 'string', max: 1000 },
+  
+  // Boolean
+  active: { type: 'boolean', default: true },
+  featured: { type: 'boolean' },
+  
+  // Dates
+  createdAt: { type: 'timestamp' },
+  launchDate: { type: 'date' },        // YYYY-MM-DD
+  lastModified: { type: 'dateTime' },  // Full datetime
+  
+  // Complex types
+  tags: { type: 'array', default: [] },
+  metadata: { type: 'object' },
+  
+  // Special types
+  image: { type: 'blob' },
+  config: { type: 'serialize' }  // Handles circular references
+});
+```
+
+### Advanced Validation
+
+```javascript
+const advancedSchema = new Schema({
+  // Custom validation
+  email: { 
+    type: 'string', 
+    required: true,
+    lowercase: true,
+    validator: (value) => {
+      if (!value.includes('@')) return 'Invalid email';
+    }
+  },
+  
+  // Conditional defaults
+  code: {
+    type: 'string',
+    default: () => 'PROD-' + Date.now()
+  },
+  
+  // Trimming and length
+  title: {
+    type: 'string',
+    trim: 100,     // Max 100 chars
+    notEmpty: true // Can't be empty string
+  },
+  
+  // Null handling
+  notes: {
+    type: 'string',
+    canBeNull: true,    // Allows null
+    emptyAsNull: true   // "" becomes null
+  }
+});
+```
+
+## Understanding the Api Class
+
+The Api class is your central hub:
+
+```javascript
+// Create with options
+const api = new Api({
+  name: 'myapp',
+  version: '1.0.0',
+  idProperty: 'id'  // Default is 'id'
+});
+
+// Add plugins
+api
+  .use(ValidationPlugin)
+  .use(MySQLPlugin, { connection: dbConfig })
+  .use(HTTPPlugin, { basePath: '/api' });
+
+// Register schemas
+api.addResource('products', productSchema);
+
+// Use programmatically - OLD WAY (still works)
+const product = await api.insert({
+  name: 'Awesome Widget',
+  price: 29.99
+}, { type: 'products' });
+
+// NEW WAY - Much more intuitive!
+const product = await api.resources.products.create({
+  name: 'Awesome Widget',
+  price: 29.99
+});
+
+// All operations available
+const found = await api.resources.products.get(123);
+const updated = await api.resources.products.update(123, { price: 39.99 });
+const results = await api.resources.products.query({ filter: { active: true } });
+await api.resources.products.delete(123);
+```
+
+## Understanding Hooks
+
+Hooks let you inject custom logic at any point:
+
+```javascript
+// Before validation
+api.hook('beforeValidate', async (context) => {
+  // context.method: 'insert', 'update', 'delete', 'get', 'query'
+  // context.data: The data being processed
+  // context.options: Options passed to the method
+  
+  if (context.method === 'insert') {
+    context.data.createdBy = context.options.userId;
+  }
+});
+
+// After validation
+api.hook('afterValidate', async (context) => {
+  // context.errors: Array of validation errors
+  
+  // Add custom validation
+  if (context.data.price > 1000 && !context.data.approved) {
+    context.errors.push({
+      field: 'price',
+      message: 'High-value items need approval',
+      code: 'NEEDS_APPROVAL'
+    });
+  }
+});
+
+// Transform results
+api.hook('transformResult', async (context) => {
+  // context.result: The data being returned
+  
+  if (context.result && context.options.type === 'products') {
+    // Add computed field
+    context.result.displayPrice = `$${context.result.price.toFixed(2)}`;
+  }
+});
+```
+
+---
+
+# Plugin Tutorials
+
+## ValidationPlugin Tutorial
+
+The ValidationPlugin is automatically included and provides schema validation.
+
+### Step 1: Basic Validation
+
+```javascript
+const api = createApi({ storage: 'memory' });
+
+// Define strict schema
+const userSchema = new Schema({
+  username: { 
+    type: 'string', 
+    required: true, 
+    min: 3, 
+    max: 20,
+    pattern: /^[a-zA-Z0-9_]+$/  // Alphanumeric + underscore only
+  },
+  age: { 
+    type: 'number', 
+    min: 13, 
+    max: 120 
+  }
+});
+
+api.addResource('users', userSchema);
+
+// This will fail validation
+try {
+  await api.insert({
+    username: 'a',  // Too short!
+    age: 200        // Too old!
+  }, { type: 'users' });
+} catch (error) {
+  console.log(error.errors);
+  // [
+  //   { field: 'username', message: 'username is too short' },
+  //   { field: 'age', message: 'age is too high' }
+  // ]
+}
+```
+
+### Step 2: Custom Validators
+
+```javascript
+const schema = new Schema({
+  password: {
+    type: 'string',
+    required: true,
+    validator: (value) => {
+      if (value.length < 8) return 'Password must be at least 8 characters';
+      if (!/[A-Z]/.test(value)) return 'Password must contain uppercase';
+      if (!/[0-9]/.test(value)) return 'Password must contain number';
+    }
+  },
+  confirmPassword: {
+    type: 'string',
+    required: true
+  }
+});
+
+// Cross-field validation
+api.hook('afterValidate', async (context) => {
+  if (context.data.password !== context.data.confirmPassword) {
+    context.errors.push({
+      field: 'confirmPassword',
+      message: 'Passwords do not match'
+    });
+  }
+});
+```
+
+### Step 3: Conditional Validation
+
+```javascript
+const orderSchema = new Schema({
+  type: { type: 'string', required: true },
+  amount: { type: 'number', required: true },
+  giftMessage: { type: 'string' }
+});
+
+api.hook('afterValidate', async (context) => {
+  const { data } = context;
+  
+  // Gift orders require a message
+  if (data.type === 'gift' && !data.giftMessage) {
+    context.errors.push({
+      field: 'giftMessage',
+      message: 'Gift orders require a message'
+    });
+  }
+});
+```
+
+### 🚀 Pro Tip: Cleaner Resource Definition
+
+Instead of adding hooks separately, you can define them with the resource:
+
+```javascript
+const userSchema = new Schema({
+  email: { type: 'string', required: true, lowercase: true },
+  password: { type: 'string', required: true },
+  role: { type: 'string', default: 'user' }
+});
+
+const userHooks = {
+  async afterValidate(context) {
+    const { data, method, errors } = context;
+    
+    // Check email uniqueness
+    if (method === 'insert' || method === 'update') {
+      const existing = await context.api.query({
+        filter: { email: data.email }
+      }, { type: 'users' });
+      
+      if (existing.meta.total > 0) {
+        errors.push({
+          field: 'email',
+          message: 'Email already exists'
+        });
+      }
+    }
+  },
+  
+  async beforeInsert(context) {
+    // Hash password
+    const bcrypt = await import('bcrypt');
+    context.data.password = await bcrypt.hash(context.data.password, 10);
+  },
+  
+  async transformResult(context) {
+    // Never return password
+    if (context.result?.attributes) {
+      delete context.result.attributes.password;
+    }
+  }
+};
+
+// Add resource with schema AND hooks together!
+api.addResource('users', userSchema, userHooks);
+```
+
+This approach keeps all resource logic in one place, making it easier to maintain!
+
+## Modular Resources (Advanced)
+
+When your API grows, you'll want to organize resources into separate files. Here's the challenge and solution:
+
+### The Challenge: Why Not Use createApi() Everywhere?
+
+You might think to do this in each resource file:
+```javascript
+// ❌ DON'T DO THIS - api/1.0.0/users.js
+const api = createApi({ ... });  // Creates NEW api instance
+api.addResource('users', schema);
+export default api;
+
+// ❌ DON'T DO THIS - api/1.0.0/products.js  
+const api = createApi({ ... });  // Creates ANOTHER api instance!
+api.addResource('products', schema);
+export default api;
+```
+
+**Problems:**
+- Each file creates a separate API instance
+- Multiple database connections (waste of resources)
+- Resources can't interact with each other
+- Configuration is duplicated everywhere
+
+### The Solution: Shared API Instances
+
+Resources in the same version should SHARE one API instance:
+
+```javascript
+// ✅ DO THIS - api/1.0.0/users.js
+import { Api, Schema } from 'jsonrestapi';
+
+// Get existing or create shared instance for v1.0.0
+const api = Api.get('myapp', '1.0.0') || new Api({ 
+  name: 'myapp', 
+  version: '1.0.0' 
+});
+
+// Configure plugins only if not already done
+if (!api.hasPlugin(HTTPPlugin)) {
+  api.use(HTTPPlugin, { basePath: '/api/1.0.0' });
+}
+
+// Define schema and hooks together
+const userSchema = new Schema({ ... });
+const userHooks = {
+  async beforeInsert(context) {
+    // Hash passwords, etc.
+  }
+};
+
+// Add resource with hooks
+api.addResource('users', userSchema, userHooks);
+
+export default api;
+```
+
+### Even Better: Using defineResource Helper
+
+The library includes a helper that manages this for you:
+
+```javascript
+// api/config.js - Shared configuration
+export const apiConfig = {
+  name: 'myapp',
+  mysql: {
+    connections: [{
+      name: 'main',
+      config: { host: 'localhost', ... }
+    }]
+  }
+};
+
+// api/1.0.0/users.js - Clean resource file
+import { Schema, defineResource } from 'jsonrestapi/resource-helper.js';
+import { apiConfig } from '../config.js';
+
+export default defineResource('1.0.0', 'users', {
+  api: apiConfig,  // Shared config
+  
+  schema: new Schema({
+    id: { type: 'id' },
+    name: { type: 'string', required: true },
+    email: { type: 'string', required: true }
+  }),
+  
+  hooks: {
+    async beforeInsert(context) {
+      // Your logic here
+    }
+  }
+});
+```
+
+### Loading Resources in Your Server
+
+```javascript
+// server.js - Super clean!
+import express from 'express';
+const app = express();
+
+// Option 1: Manual loading
+const apis = [
+  await import('./api/1.0.0/users.js'),
+  await import('./api/1.0.0/products.js'),
+];
+apis.forEach(module => module.default.mount(app));
+
+// Option 2: Auto-loading (like the old library!)
+import { loadResourcesFromPath } from './load-resources.js';
+await loadResourcesFromPath(join(__dirname, 'api'), app);
+
+app.listen(3000);
+```
+
+### Key Concepts to Remember
+
+1. **createApi()** = Creates a NEW api instance (use for simple, single-file APIs)
+2. **Api.get() || new Api()** = Gets or creates a SHARED instance (use in resource files)
+3. **defineResource()** = Helper that does the sharing for you (recommended)
+4. **One API instance per version** = All resources in v1.0.0 share the same API
+5. **api.resources.{name}** = NEW intuitive way to access resources!
+
+This way your server stays clean (one line per resource), resources are modular, and everything shares the same database connections and configuration!
+
+## Programmatic API Usage
+
+The new programmatic API makes working with resources intuitive and chainable:
+
+### Basic CRUD Operations
+
+```javascript
+// After registering a resource
+api.addResource('users', userSchema);
+
+// Create
+const user = await api.resources.users.create({
+  username: 'johndoe',
+  email: 'john@example.com'
+});
+
+// Read
+const found = await api.resources.users.get(user.data.id);
+
+// Update
+const updated = await api.resources.users.update(user.data.id, {
+  email: 'newemail@example.com'
+});
+
+// Delete
+await api.resources.users.delete(user.data.id);
+
+// Query
+const results = await api.resources.users.query({
+  filter: { active: true },
+  sort: '-createdAt',
+  page: { size: 10, number: 1 }
+});
+```
+
+### Batch Operations
+
+```javascript
+// Create multiple users at once
+const users = await api.resources.users.batch.create([
+  { username: 'user1', email: 'user1@example.com' },
+  { username: 'user2', email: 'user2@example.com' },
+  { username: 'user3', email: 'user3@example.com' }
+]);
+
+// Update multiple users
+await api.resources.users.batch.update([
+  { id: 1, data: { active: false } },
+  { id: 2, data: { active: false } }
+]);
+
+// Delete multiple users
+await api.resources.users.batch.delete([1, 2, 3]);
+```
+
+### Accessing Different Versions
+
+```javascript
+// Default: uses the current API version
+const user = await api.resources.users.get(123);
+
+// Access a specific version
+const userV1 = await api.resources.users.version('1.0.0').get(123);
+const userV2 = await api.resources.users.version('2.0.0').get(123);
+
+// This is especially useful when migrating between versions
+const oldData = await api.resources.users.version('1.0.0').query();
+for (const item of oldData.data) {
+  await api.resources.users.version('2.0.0').create(migrateData(item));
+}
+```
+
+### Direct Access to Schema and Hooks
+
+```javascript
+// Get the schema for a resource
+const schema = api.resources.users.schema;
+
+// Get the hooks for a resource
+const hooks = api.resources.users.hooks;
+
+// Check if a resource exists
+if ('users' in api.resources) {
+  console.log('Users resource is available');
+}
+
+// List all resources
+const allResources = Object.keys(api.resources);
+console.log('Available resources:', allResources);
+```
+
+### Alternative Syntax
+
+If you prefer function calls over property access:
+
+```javascript
+// Using resource() method
+const user = await api.resource('users').get(123);
+const posts = await api.resource('posts').query();
+
+// This is useful when resource names are dynamic
+const resourceName = 'users';
+const data = await api.resource(resourceName).get(123);
+```
+
+## MySQLPlugin Tutorial
+
+### Step 1: Basic Setup
+
+```javascript
+import { Api, MySQLPlugin, Schema } from 'jsonrestapi';
+
+const api = new Api();
+api.use(MySQLPlugin, {
+  connection: {
+    host: 'localhost',
+    user: 'root',
+    password: 'password',
+    database: 'myapp',
+    waitForConnections: true,
+    connectionLimit: 10,
+    queueLimit: 0
+  }
+});
+```
+
+### Step 2: Schema Synchronization
+
+```javascript
+// Define your schema
+const postSchema = new Schema({
+  id: { type: 'id' },
+  title: { type: 'string', required: true, max: 200 },
+  content: { type: 'string', text: true },  // Creates TEXT column
+  views: { type: 'number', default: 0 },
+  published: { type: 'boolean', default: false },
+  publishDate: { type: 'dateTime' },
+  tags: { type: 'array' },  // Stored as JSON
+  metadata: { type: 'object' }  // Stored as JSON
+});
+
+// Sync creates/updates the table automatically!
+await api.syncSchema(postSchema, 'posts');
+```
+
+### Step 3: Advanced MySQL Features
+
+```javascript
+// Multiple connections
+api.use(MySQLPlugin, {
+  connections: [
+    {
+      name: 'primary',
+      config: { host: 'primary.db', ... }
+    },
+    {
+      name: 'replica',
+      config: { host: 'replica.db', ... }
+    }
+  ]
+});
+
+// Use specific connection - OLD WAY
+const data = await api.query({}, {
+  type: 'posts',
+  connection: 'replica'  // Read from replica
+});
+
+// NEW WAY - Much cleaner!
+const data = await api.resources.posts.query({}, {
+  connection: 'replica'  // Read from replica
+});
+
+// Direct SQL access when needed
+const { pool } = api.getConnection('primary');
+const [rows] = await pool.query(
+  'SELECT * FROM posts WHERE MATCH(title, content) AGAINST(?)',
+  ['search term']
+);
+```
+
+### Step 4: Transactions
+
+```javascript
+const { pool } = api.getConnection();
+const connection = await pool.getConnection();
+
+try {
+  await connection.beginTransaction();
+  
+  // Create author
+  const author = await api.insert({
+    name: 'John Doe',
+    email: 'john@example.com'
+  }, {
+    type: 'authors',
+    connection  // Use transaction connection
+  });
+  
+  // Create post
+  const post = await api.insert({
+    authorId: author.data.id,
+    title: 'My First Post',
+    content: 'Hello World!'
+  }, {
+    type: 'posts',
+    connection
+  });
+  
+  await connection.commit();
+  console.log('Transaction successful!');
+  
+} catch (error) {
+  await connection.rollback();
+  console.error('Transaction failed:', error);
+} finally {
+  connection.release();
+}
+```
+
+## HTTPPlugin Tutorial
+
+### Step 1: Basic HTTP Setup
+
+```javascript
+import express from 'express';
+
+const app = express();
+const api = createApi({
+  name: 'blog',
+  version: '1.0.0',
+  storage: 'memory',
+  http: { 
+    basePath: '/api',
+    app  // Pass Express app directly
+  }
+});
+
+// That's it! Your API is now available at:
+// GET    /api/1.0.0/posts
+// GET    /api/1.0.0/posts/:id
+// POST   /api/1.0.0/posts
+// PATCH  /api/1.0.0/posts/:id
+// DELETE /api/1.0.0/posts/:id
+```
+
+### Step 2: Query Parameters
+
+```javascript
+// Filtering
+GET /api/1.0.0/posts?filter[published]=true&filter[category]=tech
+
+// Sorting (-prefix for descending)
+GET /api/1.0.0/posts?sort=-createdAt,title
+
+// Pagination
+GET /api/1.0.0/posts?page[size]=10&page[number]=2
+
+// Combined
+GET /api/1.0.0/posts?filter[published]=true&sort=-views&page[size]=5
+```
+
+### Step 3: JSON:API Format
+
+The HTTP plugin follows JSON:API specification:
+
+```javascript
+// Request body for POST/PATCH
+{
+  "data": {
+    "type": "posts",
+    "attributes": {
+      "title": "Hello World",
+      "content": "My first post"
+    }
+  }
+}
+
+// Response format
+{
+  "data": {
+    "id": "123",
+    "type": "posts",
+    "attributes": {
+      "title": "Hello World",
+      "content": "My first post",
+      "createdAt": 1639094400000
+    }
+  }
+}
+
+// Collection response
+{
+  "data": [
+    { "id": "1", "type": "posts", "attributes": {...} },
+    { "id": "2", "type": "posts", "attributes": {...} }
+  ],
+  "meta": {
+    "total": 50,
+    "pageSize": 10,
+    "pageNumber": 1,
+    "totalPages": 5
+  },
+  "links": {
+    "self": "/api/1.0.0/posts?page[number]=1",
+    "next": "/api/1.0.0/posts?page[number]=2",
+    "last": "/api/1.0.0/posts?page[number]=5"
+  }
+}
+```
+
+### Step 4: Custom Middleware
+
+```javascript
+// Add middleware to all routes
+api.useMiddleware((req, res, next) => {
+  console.log(`${req.method} ${req.path}`);
+  next();
+});
+
+// Add middleware to specific routes
+api.useRouteMiddleware('post', '/:type', async (req, res, next) => {
+  // Check API key for POST requests
+  if (!req.headers['x-api-key']) {
+    return res.status(401).json({
+      errors: [{ status: '401', title: 'API key required' }]
+    });
+  }
+  next();
+});
+```
+
+## PositioningPlugin Tutorial
+
+Perfect for drag-and-drop interfaces!
+
+### Step 1: Enable Positioning
+
+```javascript
+import { PositioningPlugin } from 'jsonrestapi';
+
+const api = createApi({ storage: 'memory' });
+api.use(PositioningPlugin);
+
+const todoSchema = new Schema({
+  id: { type: 'id' },
+  title: { type: 'string', required: true },
+  position: { type: 'number' }  // Required field!
+});
+
+api.addResource('todos', todoSchema);
+```
+
+### Step 2: Insert with Position
+
+```javascript
+// Insert at the end (default)
+const todo1 = await api.insert({
+  title: 'First task'
+}, { 
+  type: 'todos',
+  positioning: { enabled: true }
+});
+// position: 1
+
+// Insert at the end explicitly
+const todo2 = await api.insert({
+  title: 'Second task',
+  beforeId: null  // null = end
+}, { 
+  type: 'todos',
+  positioning: { enabled: true }
+});
+// position: 2
+
+// Insert before another item
+const todo3 = await api.insert({
+  title: 'Urgent task',
+  beforeId: todo1.data.id  // Insert before first task
+}, { 
+  type: 'todos',
+  positioning: { enabled: true }
+});
+// position: 1 (others shift up)
+```
+
+### Step 3: Reposition Existing Items
+
+```javascript
+// Move to end
+await api.reposition('todos', todoId, null);
+
+// Move before another item
+await api.reposition('todos', todoId, beforeTodoId);
+
+// Update with positioning
+await api.update(todoId, {
+  title: 'Updated title',
+  beforeId: anotherId  // Also reposition
+}, {
+  type: 'todos',
+  positioning: { enabled: true }
+});
+```
+
+### Step 4: Position Filters (Groups)
+
+```javascript
+// Configure positioning within groups
+api.use(PositioningPlugin, {
+  positionField: 'position',
+  positionFilters: ['projectId', 'status']  // Separate positions per project/status
+});
+
+// Now positions are scoped
+await api.insert({
+  title: 'Project A Task',
+  projectId: 1,
+  status: 'active',
+  beforeId: null
+}, { 
+  type: 'todos',
+  positioning: { enabled: true }
+});
+// This gets position 1 within project=1, status=active
+```
+
+### Step 5: Normalize Positions
+
+```javascript
+// Remove gaps in position numbers
+await api.normalizePositions('todos', {
+  projectId: 1  // Normalize within this project
+});
+
+// Get next available position
+const nextPos = await api.getNextPosition('todos', {
+  projectId: 1,
+  status: 'active'
+});
+```
+
+## VersioningPlugin Tutorial
+
+### Part 1: API Versioning
+
+```javascript
+// Version 1.0.0 of your API
+const apiV1 = createApi({
+  name: 'blog',
+  version: '1.0.0',
+  storage: 'memory'
+});
+
+const postSchemaV1 = new Schema({
+  id: { type: 'id' },
+  title: { type: 'string', required: true },
+  content: { type: 'string', required: true }
+});
+
+apiV1.addResource('posts', postSchemaV1);
+
+// Version 2.0.0 - Added author field
+const apiV2 = createApi({
+  name: 'blog',
+  version: '2.0.0',
+  storage: 'memory'
+});
+
+const postSchemaV2 = new Schema({
+  id: { type: 'id' },
+  title: { type: 'string', required: true },
+  content: { type: 'string', required: true },
+  author: { type: 'string', required: true },  // NEW!
+  tags: { type: 'array', default: [] }        // NEW!
+});
+
+apiV2.addResource('posts', postSchemaV2);
+```
+
+### Part 2: Version Selection
+
+```javascript
+// Get specific version
+const v1 = Api.get('blog', '1.0.0');
+
+// Get latest
+const latest = Api.get('blog', 'latest');
+
+// Get minimum version
+const v2plus = Api.get('blog', '2.0.0');  // Gets 2.0.0 or higher
+
+// Use in your app
+async function createPost(data) {
+  // Auto-select version based on data
+  const hasAuthor = 'author' in data;
+  const api = Api.get('blog', hasAuthor ? '2.0.0' : '1.0.0');
+  
+  return api.insert(data, { type: 'posts' });
+}
+```
+
+### Part 3: Resource Versioning
+
+```javascript
+import { VersioningPlugin } from 'jsonrestapi';
+
+const api = createApi({ storage: 'mysql' });
+api.use(VersioningPlugin, {
+  trackHistory: true,
+  optimisticLocking: true,
+  versionField: 'version',
+  lastModifiedField: 'lastModified',
+  modifiedByField: 'modifiedBy'
+});
+
+// Automatic version tracking
+const post = await api.insert({
+  title: 'Original Title',
+  content: 'Original content'
+}, { 
+  type: 'posts',
+  userId: 'user123'
+});
+// version: 1, modifiedBy: 'user123'
+
+// Update increments version
+const updated = await api.update(post.data.id, {
+  title: 'Updated Title'
+}, { 
+  type: 'posts',
+  userId: 'user456'
+});
+// version: 2, modifiedBy: 'user456'
+```
+
+### Part 4: Version History
+
+```javascript
+// Get full history
+const history = await api.getVersionHistory('posts', postId);
+// Returns all versions with timestamps
+
+// Restore old version
+await api.restoreVersion('posts', postId, 1);
+// Post is now back to version 1 content (as version 3)
+
+// Compare versions
+const diff = await api.diffVersions('posts', postId, 1, 2);
+console.log(diff);
+// {
+//   version1: 1,
+//   version2: 2,
+//   changes: [
+//     { field: 'title', oldValue: 'Original Title', newValue: 'Updated Title' }
+//   ]
+// }
+```
+
+### Part 5: Optimistic Locking
+
+```javascript
+// Prevent concurrent updates
+const post = await api.get(postId, { type: 'posts' });
+
+try {
+  await api.update(postId, {
+    title: 'New Title',
+    version: post.data.attributes.version  // Include current version
+  }, { type: 'posts' });
+} catch (error) {
+  if (error.code === 'VERSION_CONFLICT') {
+    console.log('Someone else updated this post!');
+    // Reload and try again
+  }
+}
+```
+
+## SecurityPlugin Tutorial
+
+### Step 1: Basic Security
+
+```javascript
+import { SecurityPlugin } from 'jsonrestapi';
+
+api.use(SecurityPlugin, {
+  // Rate limiting
+  rateLimit: {
+    windowMs: 15 * 60 * 1000,  // 15 minutes
+    max: 100,  // 100 requests per window
+    message: 'Too many requests'
+  },
+  
+  // CORS
+  cors: {
+    origin: ['https://app.example.com', 'http://localhost:3000'],
+    credentials: true
+  },
+  
+  // Authentication
+  authentication: {
+    type: 'bearer',  // or 'apikey', 'basic'
+    required: true,
+    header: 'Authorization'
+  }
+});
+```
+
+### Step 2: Token Authentication
+
+```javascript
+api.use(SecurityPlugin, {
+  authentication: {
+    type: 'bearer',
+    required: true
+  },
+  verifyToken: async (token, context) => {
+    // Verify JWT token
+    try {
+      const decoded = jwt.verify(token, process.env.JWT_SECRET);
+      return {
+        id: decoded.userId,
+        email: decoded.email,
+        roles: decoded.roles
+      };
+    } catch (error) {
+      throw new Error('Invalid token');
+    }
+  }
+});
+
+// Token is now available in hooks
+api.hook('beforeInsert', async (context) => {
+  context.data.createdBy = context.options.user?.id;
+});
+```
+
+### Step 3: API Key Authentication
+
+```javascript
+api.use(SecurityPlugin, {
+  authentication: {
+    type: 'apikey',
+    header: 'X-API-Key',
+    queryParam: 'apikey'  // Also allow ?apikey=xxx
+  },
+  verifyToken: async (apiKey) => {
+    // Look up API key in database
+    const keyData = await findApiKey(apiKey);
+    if (!keyData) throw new Error('Invalid API key');
+    
+    return {
+      id: keyData.userId,
+      permissions: keyData.permissions
+    };
+  }
+});
+```
+
+### Step 4: Public/Private Routes
+
+```javascript
+api.use(SecurityPlugin, {
+  publicRead: true,  // Allow GET without auth
+  authentication: {
+    type: 'bearer',
+    required: true
+  }
+});
+
+// Or fine-grained control
+api.hook('beforeValidate', async (context) => {
+  const isPublic = 
+    context.options.type === 'posts' && 
+    context.method === 'query';
+    
+  if (!isPublic && !context.options.authenticated) {
+    context.errors.push({
+      field: null,
+      message: 'Authentication required',
+      code: 'AUTH_REQUIRED'
+    });
+  }
+});
+```
+
+### Step 5: Security Headers
+
+The SecurityPlugin automatically adds:
+- `X-Content-Type-Options: nosniff`
+- `X-Frame-Options: DENY`
+- `X-XSS-Protection: 1; mode=block`
+- `Strict-Transport-Security: max-age=31536000`
+- `Content-Security-Policy` with safe defaults
+
+## LoggingPlugin Tutorial
+
+### Step 1: Basic Logging
+
+```javascript
+import { LoggingPlugin } from 'jsonrestapi';
+
+api.use(LoggingPlugin, {
+  level: 'info',  // error, warn, info, debug
+  format: 'json',  // or 'pretty'
+  includeRequest: true,
+  includeResponse: true,
+  includeTiming: true
+});
+
+// Now all operations are logged!
+```
+
+### Step 2: Custom Logger
+
+```javascript
+import winston from 'winston';
+
+const logger = winston.createLogger({
+  level: 'info',
+  format: winston.format.json(),
+  transports: [
+    new winston.transports.File({ filename: 'error.log', level: 'error' }),
+    new winston.transports.File({ filename: 'combined.log' })
+  ]
+});
+
+api.use(LoggingPlugin, {
+  logger,  // Use Winston instead of console
+  sensitiveFields: ['password', 'creditCard', 'ssn']
+});
+```
+
+### Step 3: Audit Logging
+
+```javascript
+api.use(LoggingPlugin, {
+  auditLog: true,  // Log all data changes
+  level: 'info'
+});
+
+// Creates detailed audit trail
+// INFO: Resource created {
+//   audit: true,
+//   operation: 'create',
+//   type: 'users',
+//   id: '123',
+//   userId: 'admin',
+//   changes: { name: 'John', email: 'john@example.com' }
+// }
+```
+
+### Step 4: Manual Logging
+
+```javascript
+// Use the logger directly
+api.log.info('Processing payment', {
+  orderId: '12345',
+  amount: 99.99,
+  currency: 'USD'
+});
+
+api.log.error('Payment failed', {
+  orderId: '12345',
+  error: 'Insufficient funds',
+  attempts: 3
+});
+
+api.log.debug('Cache hit', {
+  key: 'user:123',
+  ttl: 3600
+});
+```
+
+## OpenAPIPlugin Tutorial
+
+### Step 1: Generate Documentation
+
+```javascript
+import { OpenAPIPlugin } from 'jsonrestapi';
+
+api.use(OpenAPIPlugin, {
+  title: 'My Awesome API',
+  version: '1.0.0',
+  description: 'The best API ever created',
+  servers: [
+    { url: 'https://api.example.com', description: 'Production' },
+    { url: 'http://localhost:3000', description: 'Development' }
+  ],
+  contact: {
+    name: 'API Support',
+    email: 'support@example.com'
+  }
+});
+
+// Documentation available at:
+// GET /api/docs      - Swagger UI
+// GET /api/openapi.json - OpenAPI spec
+```
+
+### Step 2: Enhance Schema Documentation
+
+```javascript
+const userSchema = new Schema({
+  id: { 
+    type: 'id',
+    description: 'Unique user identifier'
+  },
+  email: { 
+    type: 'string',
+    required: true,
+    description: 'User email address',
+    example: 'user@example.com'
+  },
+  role: {
+    type: 'string',
+    enum: ['user', 'admin', 'moderator'],
+    description: 'User role in the system',
+    default: 'user'
+  }
+});
+
+// This generates rich OpenAPI documentation!
+```
+
+---
+
+# Advanced Features
+
+## Cross-API Communication
+
+APIs can talk to each other!
+
+```javascript
+// Users API
+const usersApi = createApi({
+  name: 'users',
+  version: '1.0.0',
+  storage: 'mysql'
+});
+
+// Orders API
+const ordersApi = createApi({
+  name: 'orders',
+  version: '1.0.0',
+  storage: 'mysql'
+});
+
+// Orders can access users!
+ordersApi.hook('afterInsert', async (context) => {
+  if (context.result) {
+    // Automatically gets compatible users API
+    const usersApi = ordersApi.apis.users;
+    
+    // Get user details
+    const user = await usersApi.get(
+      context.result.userId, 
+      { type: 'users' }
+    );
+    
+    // Send confirmation email
+    await sendEmail(user.data.attributes.email, {
+      subject: 'Order Confirmed',
+      orderId: context.result.id
+    });
+  }
+});
+```
+
+## Creating Custom Plugins
+
+Build your own plugins!
+
+```javascript
+const CachePlugin = {
+  install(api, options = {}) {
+    const cache = new Map();
+    const ttl = options.ttl || 60000;  // 1 minute default
+    
+    // Cache GET requests
+    api.hook('beforeGet', async (context) => {
+      const key = `${context.options.type}:${context.id}`;
+      const cached = cache.get(key);
+      
+      if (cached && cached.expires > Date.now()) {
+        context.result = cached.data;
+        context.fromCache = true;
+        return false;  // Skip further processing
+      }
+    });
+    
+    // Store in cache after GET
+    api.hook('afterGet', async (context) => {
+      if (!context.fromCache && context.result) {
+        const key = `${context.options.type}:${context.id}`;
+        cache.set(key, {
+          data: context.result,
+          expires: Date.now() + ttl
+        });
+      }
+    });
+    
+    // Invalidate on update/delete
+    api.hook('afterUpdate', async (context) => {
+      const key = `${context.options.type}:${context.id}`;
+      cache.delete(key);
+    });
+    
+    api.hook('afterDelete', async (context) => {
+      const key = `${context.options.type}:${context.id}`;
+      cache.delete(key);
+    });
+    
+    // Add cache methods
+    api.clearCache = () => cache.clear();
+    api.getCacheSize = () => cache.size;
+  }
+};
+
+// Use it!
+api.use(CachePlugin, { ttl: 300000 });  // 5 minutes
+```
+
+## Complex Validation Scenarios
+
+```javascript
+// Product with complex rules
+const productSchema = new Schema({
+  name: { type: 'string', required: true },
+  price: { type: 'number', required: true, min: 0 },
+  salePrice: { type: 'number', min: 0 },
+  category: { type: 'string', required: true },
+  stock: { type: 'number', default: 0, min: 0 },
+  sku: { type: 'string', required: true }
+});
+
+// Multi-field validation
+api.hook('afterValidate', async (context) => {
+  const { data, errors, method } = context;
+  
+  // Sale price must be less than regular price
+  if (data.salePrice && data.salePrice >= data.price) {
+    errors.push({
+      field: 'salePrice',
+      message: 'Sale price must be less than regular price'
+    });
+  }
+  
+  // SKU must be unique
+  if ((method === 'insert' || method === 'update') && data.sku) {
+    const existing = await api.query({
+      filter: { sku: data.sku }
+    }, { type: 'products' });
+    
+    const isDuplicate = method === 'insert' 
+      ? existing.data.length > 0
+      : existing.data.some(p => p.id !== context.id);
+      
+    if (isDuplicate) {
+      errors.push({
+        field: 'sku',
+        message: 'SKU already exists'
+      });
+    }
+  }
+  
+  // Category-specific validation
+  if (data.category === 'electronics' && !data.warrantyPeriod) {
+    errors.push({
+      field: 'warrantyPeriod',
+      message: 'Electronics must have warranty period'
+    });
+  }
+});
+```
+
+## Performance Optimization
+
+```javascript
+// Batch operations
+async function importProducts(products) {
+  const batchSize = 100;
+  const results = [];
+  
+  for (let i = 0; i < products.length; i += batchSize) {
+    const batch = products.slice(i, i + batchSize);
+    
+    // Process batch in parallel
+    const batchResults = await Promise.all(
+      batch.map(product => 
+        api.insert(product, { type: 'products' })
+          .catch(error => ({ error, product }))
+      )
+    );
+    
+    results.push(...batchResults);
+    
+    // Progress
+    console.log(`Imported ${Math.min(i + batchSize, products.length)} / ${products.length}`);
+  }
+  
+  return results;
+}
+
+// Optimized queries
+const results = await api.query({
+  filter: { category: 'electronics', active: true },
+  sort: '-price',
+  page: { size: 50 }  // Don't fetch everything!
+}, {
+  type: 'products',
+  fields: ['id', 'name', 'price']  // Only needed fields
+});
+```
+
+## Error Recovery
+
+```javascript
+// Retry logic
+async function reliableInsert(data, options, maxRetries = 3) {
+  let lastError;
+  
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      return await api.insert(data, options);
+    } catch (error) {
+      lastError = error;
+      
+      // Don't retry validation errors
+      if (error.status === 422) throw error;
+      
+      // Exponential backoff
+      const delay = Math.min(1000 * Math.pow(2, attempt - 1), 10000);
+      console.log(`Attempt ${attempt} failed, retrying in ${delay}ms...`);
+      
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+  
+  throw lastError;
+}
+
+// Graceful degradation
+async function getProductWithFallback(id) {
+  try {
+    // Try primary database
+    return await api.get(id, { 
+      type: 'products',
+      connection: 'primary'
+    });
+  } catch (error) {
+    console.warn('Primary database failed, trying cache...');
+    
+    try {
+      // Try cache
+      return await cacheApi.get(id, { type: 'products' });
+    } catch (cacheError) {
+      console.error('Cache also failed, returning degraded response');
+      
+      // Return degraded response
+      return {
+        data: {
+          id,
+          type: 'products',
+          attributes: {
+            name: 'Product temporarily unavailable',
+            available: false
+          }
+        }
+      };
+    }
+  }
+}
+```
+
+## Testing Your API
+
+```javascript
+import { createApi, Schema } from 'jsonrestapi';
+import { describe, it, expect, beforeEach } from 'vitest';
+
+describe('User API', () => {
+  let api;
+  
+  beforeEach(() => {
+    // Fresh API for each test
+    api = createApi({
+      name: 'test',
+      version: '1.0.0',
+      storage: 'memory'
+    });
+    
+    const userSchema = new Schema({
+      id: { type: 'id' },
+      email: { type: 'string', required: true },
+      name: { type: 'string', required: true }
+    });
+    
+    api.addResource('users', userSchema);
+  });
+  
+  it('should create a user', async () => {
+    const user = await api.insert({
+      email: 'test@example.com',
+      name: 'Test User'
+    }, { type: 'users' });
+    
+    expect(user.data.attributes.email).toBe('test@example.com');
+    expect(user.data.id).toBeDefined();
+  });
+  
+  it('should validate required fields', async () => {
+    await expect(
+      api.insert({ email: 'test@example.com' }, { type: 'users' })
+    ).rejects.toThrow();
+  });
+  
+  it('should update users', async () => {
+    const user = await api.insert({
+      email: 'test@example.com',
+      name: 'Original Name'
+    }, { type: 'users' });
+    
+    const updated = await api.update(user.data.id, {
+      name: 'Updated Name'
+    }, { type: 'users' });
+    
+    expect(updated.data.attributes.name).toBe('Updated Name');
+  });
+});
+```
+
+---
+
+Congratulations! You've mastered the JSON REST API library! 🎉
+
+Remember:
+- Start simple with memory storage
+- Add MySQL when you need persistence
+- Use plugins to add features incrementally
+- Hooks are your friends for custom logic
+- The library handles versioning automatically
+- Always validate your data
+- Security first!
+
+Happy coding! 🚀