json-rest-api 1.0.10 → 1.0.13

package/docs/GUIDE/GUIDE_6_Positioning.md

@@ -60,8 +60,7 @@ import { RestApiKnexPlugin } from './plugins/core/rest-api-knex-plugin.js';
 import { PositioningPlugin } from './plugins/core/rest-api-positioning-plugin.js';
 
 const api = new Api({
-  name: 'my-api',
-  version: '1.0.0'
+  name: 'my-api'
 });
 
 // Core plugins
@@ -657,7 +656,6 @@ Enable debug logging to see position calculations:
 ```javascript
 const api = new Api({
   name: 'my-api',
-  version: '1.0.0',
   logging: { level: 'debug' }
 });
 ```

package/docs/GUIDE/GUIDE_7_Hooks_Data_Management_And_Plugins.md

@@ -109,7 +109,6 @@ api.customize({
   apiMethods: {
     healthCheck: async ({ vars, scopes }) => ({
       status: 'ok',
-      version: vars.apiVersion || '1.0.0',
       environment: vars.environment,
       timestamp: new Date().toISOString(),
       resources: Object.keys(scopes)
@@ -611,6 +610,7 @@ Used for creating new resources.
 - Can set defaults or compute values
 
 **Note**: After validation, attributes are stored in `context.inputRecord.data.attributes`, not directly in `context.attributes`.
+**Note**: `context.minimalRecord` is always a JSON:API resource object; for POST requests it is a snapshot of the incoming payload (`{ type, id?, attributes, relationships }`).
 
 **Example**:
 ```javascript
@@ -781,7 +781,7 @@ hooks: {
     if (context.method === 'put' && context.inputRecord) {
       // Prevent changing the author (check if belongsTo relationship changed)
       const newAuthorId = context.belongsToUpdates?.author_id;
-      const currentAuthorId = context.minimalRecord?.data?.relationships?.author?.data?.id;
+      const currentAuthorId = context.minimalRecord?.relationships?.author?.data?.id;
       if (newAuthorId && newAuthorId !== currentAuthorId) {
         throw new Error('Cannot change post author');
       }
@@ -899,7 +899,7 @@ Used for partially updating a resource.
 - `belongsToUpdates` - Modify foreign key values (if any)
 - Can add computed values or prevent updates
 
-**Note**: For PATCH, `context.inputRecord.data.attributes` contains only the fields being updated. Use `context.minimalRecord.data.attributes` to access the complete current record.
+**Note**: For PATCH, `context.inputRecord.data.attributes` contains only the fields being updated. Use `context.minimalRecord.attributes` to access the complete current record.
 
 **Example**:
 ```javascript
@@ -908,7 +908,7 @@ hooks: {
     if (context.method === 'patch' && context.inputRecord) {
       // If status is being changed to published, set publish date
       if (context.inputRecord.data.attributes.status === 'published' && 
-          context.minimalRecord?.data?.attributes?.status !== 'published') {
+        context.minimalRecord?.attributes?.status !== 'published') {
         context.inputRecord.data.attributes.published_at = new Date().toISOString();
       }
       
@@ -1487,4 +1487,3 @@ hooks: {
 ---
 
 [Back to Guide](./README.md)
-

package/docs/GUIDE/GUIDE_X_Bulk_Operations.md

@@ -39,7 +39,6 @@ const knex = knexLib({
 // Create API instance
 const api = new Api({
   name: 'book-catalog-api',
-  version: '1.0.0'
 });
 
 // Install plugins in order
@@ -81,8 +80,8 @@ await api.addResource('countries', {
     code: { type: 'string', max: 2, unique: true }
   },
   relationships: {
-    publishers: { hasMany: 'publishers', foreignKey: 'country_id' },
-    books: { hasMany: 'books', foreignKey: 'country_id' }
+    publishers: { type: 'hasMany', target: 'publishers', foreignKey: 'country_id' },
+    books: { type: 'hasMany', target: 'books', foreignKey: 'country_id' }
   }
 });
 
@@ -93,7 +92,7 @@ await api.addResource('publishers', {
     country_id: { type: 'number', nullable: true, belongsTo: 'countries', as: 'country' }
   },
   relationships: {
-    books: { hasMany: 'books', foreignKey: 'publisher_id' }
+    books: { type: 'hasMany', target: 'books', foreignKey: 'publisher_id' }
   }
 });
 
@@ -103,7 +102,12 @@ await api.addResource('authors', {
     name: { type: 'string', required: true, max: 200 }
   },
   relationships: {
-    books: { hasMany: 'books', through: 'book_authors', foreignKey: 'author_id', otherKey: 'book_id' }
+    books: { 
+      type: 'manyToMany',
+      through: 'book_authors',
+      foreignKey: 'author_id',
+      otherKey: 'book_id'
+    }
   }
 });
 
@@ -115,7 +119,12 @@ await api.addResource('books', {
     publisher_id: { type: 'number', nullable: true, belongsTo: 'publishers', as: 'publisher' }
   },
   relationships: {
-    authors: { hasMany: 'authors', through: 'book_authors', foreignKey: 'book_id', otherKey: 'author_id' }
+    authors: { 
+      type: 'manyToMany',
+      through: 'book_authors',
+      foreignKey: 'book_id',
+      otherKey: 'author_id'
+    }
   }
 });
 

package/docs/GUIDE/GUIDE_X_Cors.md

@@ -115,7 +115,7 @@ import express from 'express';
 import knex from 'knex';
 
 // Create API instance
-const api = new Api({ name: 'my-api', version: '1.0.0' });
+const api = new Api({ name: 'my-api' });
 
 // Set up database
 const db = knex({
@@ -502,13 +502,11 @@ await api.use(CorsPlugin, {
     allowedHeaders: [
       'Content-Type',
       'Authorization',
-      'X-API-Version',        // Client specifies API version
       'X-Request-ID',         // For request tracking
       'X-Client-ID',          // Identify different client apps
       'X-Feature-Flags'       // Client-specific features
     ],
     exposedHeaders: [
-      'X-API-Version',        // Confirm which version was used
       'X-Deprecated',         // Warn about deprecated endpoints
       'X-Request-ID',         // For debugging
       'X-Cache-Status',       // Was this cached?
@@ -1155,7 +1153,7 @@ await apiV2.use(ExpressPlugin, {
 await apiV2.use(CorsPlugin, {
   'rest-api-cors': {
     origin: 'https://app.example.com', // v2 doesn't support legacy
-    allowedHeaders: ['Content-Type', 'Authorization', 'X-API-Version']
+    allowedHeaders: ['Content-Type', 'Authorization']
   }
 });
 
@@ -1468,7 +1466,6 @@ headers['Access-Control-Expose-Headers'] = [
   'X-RateLimit-Reset',
   
   // API Info
-  'X-API-Version',
   'X-Response-Time',
   'X-Request-ID'
 ].join(', ');

package/docs/GUIDE/GUIDE_X_File_Uploads.md

@@ -37,7 +37,7 @@ import { RestApiPlugin, FileHandlingPlugin, ExpressPlugin } from 'json-rest-api'
 import { LocalStorage } from 'json-rest-api/plugins/storage/local-storage.js';
 
 // Create API
-const api = new Api({ name: 'my-api', version: '1.0.0' });
+const api = new Api({ name: 'my-api'});
 
 // Create storage
 const storage = new LocalStorage({
@@ -416,7 +416,7 @@ import { LocalStorage } from 'json-rest-api/plugins/storage/local-storage.js';
 import express from 'express';
 
 // Setup
-const api = new Api({ name: 'image-api', version: '1.0.0' });
+const api = new Api({ name: 'image-api' });
 const storage = new LocalStorage({
   directory: './uploads/images',
   baseUrl: 'http://localhost:3000/uploads/images'
@@ -641,7 +641,6 @@ Enable debug logging to see what's happening:
 ```javascript
 const api = new Api({
   name: 'my-api',
-  version: '1.0.0',
   logLevel: 'debug'  // or 'trace' for more detail
 });
 ```

package/docs/GUIDE/GUIDE_X_Multihome.md

@@ -80,8 +80,7 @@ import { MultiHomePlugin } from './plugins/core/multihome-plugin.js';
 
 ```javascript
 const api = new Api({ 
-  name: 'my-multi-tenant-api', 
-  version: '1.0.0' 
+  name: 'my-multi-tenant-api',
 });
 
 // Install required plugins first
@@ -471,7 +470,6 @@ Enable detailed logging to troubleshoot:
 ```javascript
 const api = new Api({
   name: 'my-api',
-  version: '1.0.0',
   logging: { level: 'trace' }
 });
 ```
@@ -589,7 +587,6 @@ const db = knex({
 // Create API
 const api = new Api({ 
   name: 'saas-api', 
-  version: '1.0.0',
   logging: { level: 'info' }
 });
 

package/docs/GUIDE/GUIDE_X_SocketIO.md

@@ -47,7 +47,6 @@ import { JWTAuthPlugin } from 'json-rest-api/plugins/jwt-auth';
 // Create your API instance
 const api = new Api({
   name: 'my-api',
-  version: '1.0.0'
 });
 
 // Add required plugins
@@ -983,7 +982,6 @@ Enable debug logging to troubleshoot:
 // Server-side
 const api = new Api({
   name: 'my-api',
-  version: '1.0.0',
   logging: { level: 'debug' }
 });
 

package/docs/GUIDE/GUIDE_X_URL_Management.md

@@ -0,0 +1,317 @@
+# URL Management in JSON REST API
+
+## Overview
+
+The JSON REST API automatically generates appropriate URLs for all resources in JSON:API responses. URLs are calculated **per-request** based on the incoming request headers, ensuring correct URLs in all deployment scenarios without configuration.
+
+## How It Works
+
+### Automatic URL Detection
+
+URLs in responses (links, hrefs) are automatically generated based on:
+
+1. **Protocol**: Detected from `X-Forwarded-Proto` header or request protocol
+2. **Host**: Detected from `X-Forwarded-Host` or `Host` header  
+3. **Mount Path**: Where your API routes are mounted (e.g., `/api`)
+
+```javascript
+// Example: Simple setup - no URL configuration needed!
+await api.use(RestApiPlugin);
+await api.use(RestApiKnexPlugin, { knex });
+await api.use(ExpressPlugin, { mountPath: '/api' });
+```
+
+### Different Deployment Scenarios
+
+#### Local Development
+```
+Request: GET http://localhost:3000/api/books
+Response links: http://localhost:3000/api/books/1
+```
+
+#### Production with Domain
+```
+Request: GET https://api.example.com/api/books
+Response links: https://api.example.com/api/books/1
+```
+
+#### Behind Reverse Proxy (Nginx/Apache)
+```nginx
+# Nginx configuration
+proxy_set_header X-Forwarded-Proto $scheme;
+proxy_set_header X-Forwarded-Host $host;
+proxy_pass http://backend:3000;
+```
+
+```
+Request headers:
+  X-Forwarded-Proto: https
+  X-Forwarded-Host: api.example.com
+Response links: https://api.example.com/api/books/1
+```
+
+#### Multi-Tenant SaaS
+Each tenant gets their own domain in responses automatically:
+```
+Tenant A request: GET https://customer-a.api.com/api/books
+Response links: https://customer-a.api.com/api/books/1
+
+Tenant B request: GET https://customer-b.api.com/api/books  
+Response links: https://customer-b.api.com/api/books/1
+```
+
+## Advanced: Custom URL Override
+
+For complex deployments (API gateways, CDNs, etc.), you can override URL generation using hooks.
+
+### Recommended Method: API Hooks (Best Practice)
+
+Define a hook when creating your API to handle URL overrides:
+
+```javascript
+const api = new Api({ 
+  name: 'my-api',
+  
+  // Define hooks at API creation time
+  hooks: {
+    'transport:request': [
+      async (payload) => {
+        const { context, req } = payload;
+        
+        // Example: Override based on custom header
+        if (req?.headers?.['x-public-url']) {
+          context.urlPrefixOverride = req.headers['x-public-url'];
+        }
+        
+        // Example: API versioning
+        if (req?.headers?.['x-api-version'] === 'v2') {
+          context.urlPrefixOverride = 'https://api.example.com/v2';
+        }
+        
+        // Example: Multi-tenant based on host
+        const host = req?.hostname;
+        if (host?.includes('tenant-a')) {
+          context.urlPrefixOverride = 'https://tenant-a.api.com/api';
+        }
+        
+        // Example: Environment-based override
+        if (process.env.PUBLIC_API_URL) {
+          context.urlPrefixOverride = process.env.PUBLIC_API_URL;
+        }
+        
+        return payload;
+      }
+    ]
+  }
+});
+
+// Then use plugins normally
+await api.use(RestApiPlugin);
+await api.use(RestApiKnexPlugin, { knex });
+await api.use(ExpressPlugin, { mountPath: '/api' });
+```
+
+### Alternative Method: Express Middleware
+
+If you cannot use hooks, you can use Express middleware before mounting the API:
+
+```javascript
+app.use((req, res, next) => {
+  // Set urlPrefixOverride on the request
+  if (req.headers['x-public-url']) {
+    req.urlPrefixOverride = req.headers['x-public-url'];
+  }
+  next();
+});
+
+// Then mount your API
+app.use(api.http.express.router);
+```
+
+### Common Use Cases for Override
+
+1. **API Gateway with Path Rewriting**
+   ```javascript
+   hooks: {
+     'transport:request': [async (payload) => {
+       if (payload.req?.headers?.['x-forwarded-prefix'] === '/v2') {
+         payload.context.urlPrefixOverride = 'https://api.company.com/v2';
+       }
+       return payload;
+     }]
+   }
+   ```
+
+2. **CDN with Different Public URL**
+   ```javascript
+   hooks: {
+     'transport:request': [async (payload) => {
+       if (payload.req?.headers?.['x-cdn-host']) {
+         payload.context.urlPrefixOverride = `https://${payload.req.headers['x-cdn-host']}/api`;
+       }
+       return payload;
+     }]
+   }
+   ```
+
+3. **Multi-Tenant SaaS**
+   ```javascript
+   hooks: {
+     'transport:request': [async (payload) => {
+       const { context, req } = payload;
+       const tenant = req?.hostname?.split('.')[0];
+       if (tenant && tenant !== 'api') {
+         context.urlPrefixOverride = `https://${tenant}.api.com/api`;
+       }
+       return payload;
+     }]
+   }
+   ```
+
+4. **Environment-Based URLs**
+   ```javascript
+   hooks: {
+     'transport:request': [async (payload) => {
+       // Force production URLs in staging for testing
+       if (process.env.NODE_ENV === 'staging' && process.env.PRODUCTION_URL) {
+         payload.context.urlPrefixOverride = process.env.PRODUCTION_URL;
+       }
+       return payload;
+     }]
+   }
+   ```
+
+## What You DON'T Need to Configure
+
+❌ **No need for:**
+- Static URL configuration
+- Per-environment URL settings
+- Manual protocol detection
+- Proxy configuration in the API
+
+The system automatically handles:
+- HTTP vs HTTPS detection
+- Domain detection from headers
+- Proxy headers (`X-Forwarded-*`)
+- Port numbers
+- Mount paths
+
+## URL Generation Examples
+
+### Resource URLs
+```javascript
+// Generated in responses as:
+{
+  "type": "books",
+  "id": "123",
+  "attributes": { ... },
+  "links": {
+    "self": "https://api.example.com/api/books/123"  // Automatically generated
+  }
+}
+```
+
+### Relationship URLs
+```javascript
+{
+  "relationships": {
+    "author": {
+      "links": {
+        "self": "https://api.example.com/api/books/123/relationships/author",
+        "related": "https://api.example.com/api/books/123/author"
+      }
+    }
+  }
+}
+```
+
+### Pagination URLs
+```javascript
+{
+  "links": {
+    "self": "https://api.example.com/api/books?page[number]=2",
+    "first": "https://api.example.com/api/books?page[number]=1",
+    "prev": "https://api.example.com/api/books?page[number]=1",
+    "next": "https://api.example.com/api/books?page[number]=3",
+    "last": "https://api.example.com/api/books?page[number]=10"
+  }
+}
+```
+
+## Benefits of Per-Request URL Generation
+
+1. **Zero Configuration**: Works correctly out of the box
+2. **Multi-Domain Safe**: Each request gets appropriate URLs
+3. **Proxy Friendly**: Automatically handles reverse proxies
+4. **Flexible**: Override when needed for complex scenarios
+5. **Stateless**: No global state that can be contaminated
+
+## Troubleshooting
+
+### URLs are showing localhost in production
+- Ensure your reverse proxy is setting `X-Forwarded-Host` and `X-Forwarded-Proto` headers
+- Check that these headers are being passed through to your application
+
+### Need different URLs for different environments
+- Use the `urlPrefixOverride` pattern with environment variables
+- Set `PUBLIC_API_URL` environment variable appropriately
+
+### API Gateway stripping paths
+- Use middleware to set `req.urlPrefixOverride` with the full public path
+- Include any path prefixes that the gateway strips
+
+## Complete Working Example
+
+Here's a full example showing URL override with hooks:
+
+```javascript
+import { Api } from 'hooked-api';
+import { RestApiPlugin, RestApiKnexPlugin, ExpressPlugin } from 'json-rest-api';
+import express from 'express';
+
+// Create API with URL override hook
+const api = new Api({ 
+  name: 'my-api',
+  hooks: {
+    'transport:request': [
+      async (payload) => {
+        const { context, req } = payload;
+        
+        // Check for custom public URL header
+        if (req?.headers?.['x-public-url']) {
+          context.urlPrefixOverride = req.headers['x-public-url'];
+        }
+        
+        return payload;
+      }
+    ]
+  }
+});
+
+// Install plugins
+await api.use(RestApiPlugin);
+await api.use(RestApiKnexPlugin, { knex });
+await api.use(ExpressPlugin, { mountPath: '/api' });
+
+// Define resources...
+await api.addResource('books', { /* schema */ });
+
+// Create Express app
+const app = express();
+app.use(api.http.express.router);
+app.listen(3000);
+```
+
+Now your API automatically handles:
+- `curl http://localhost:3000/api/books` → URLs: `http://localhost:3000/api/books/1`
+- `curl -H "X-Public-URL: https://cdn.example.com/api" http://localhost:3000/api/books` → URLs: `https://cdn.example.com/api/books/1`
+
+## Summary
+
+The JSON REST API's URL management system provides:
+- **Automatic detection** for 99% of use cases
+- **Hook-based override** for complex deployments
+- **Per-request isolation** preventing cross-domain issues
+- **No configuration** required for standard deployments
+
+Just set your `mountPath` in the Express plugin and optionally define hooks for custom scenarios!

package/docs/GUIDE/index.md

@@ -45,6 +45,9 @@ Welcome to the comprehensive guide for JSON REST API. This guide will walk you t
 - **[Socket.IO Integration](GUIDE_X_SocketIO.md)**  
   Add real-time capabilities to your API with WebSocket support.
 
+- **[URL Management](GUIDE_X_URL_Management.md)**  
+  Configure URL generation for proxies, CDNs, and multi-tenant scenarios.
+
 - **[Appendices](GUIDE_Y_Appendices.md)**  
   Reference material, troubleshooting, and additional resources.
 

package/docs/QUICKSTART.md

@@ -44,10 +44,10 @@ const knex = knexLib({
 });
 
 // Create API instance
-const api = new Api({ name: 'book-catalog-api', version: '1.0.0' });
+const api = new Api({ name: 'book-catalog-api'});
 
 // Install plugins
-await api.use(RestApiPlugin, { publicBaseUrl: '/api' }); // Public URL might be different in case of proxies etc.
+await api.use(RestApiPlugin); // URLs auto-detected from request headers
 await api.use(RestApiKnexPlugin, { knex });
 await api.use(ExpressPlugin, {  mountPath: '/api' }); // Added: Express Plugin
 
@@ -78,7 +78,7 @@ await api.addResource('publishers', {
   },
   relationships: {
     // A publisher has many authors
-    authors: { hasMany: 'authors', foreignKey: 'publisher_id' },
+    authors: { type: 'hasMany', target: 'authors', foreignKey: 'publisher_id' },
   },
   searchSchema: { // Adding search schema for publishers
     name: { type: 'string', filterOperator: 'like' }
@@ -107,7 +107,7 @@ await api.resources.authors.createKnexTable();
 
 ```bash
 $ node index.js 
-2025-08-01T00:25:50.730Z [INFO] [book-catalog-api] Installing plugin 'rest-api' { options: { publicBaseUrl: '/api/1.0' } }
+2025-08-01T00:25:50.730Z [INFO] [book-catalog-api] Installing plugin 'rest-api'
 2025-08-01T00:25:50.736Z [INFO] [book-catalog-api] Plugin 'rest-api' installed successfully { duration: '2ms' }
 2025-08-01T00:25:50.736Z [INFO] [book-catalog-api] Installing plugin 'rest-api-knex' { options: '[Object with methods]' }
 2025-08-01T00:25:50.745Z [INFO] [book-catalog-api:plugin:rest-api-knex] Database capabilities detected: { database: 'SQLite', version: '3.50.2', windowFunctions: true }
@@ -162,7 +162,7 @@ console.log('JSON:API response:', inspect(oxfordResult));
 const authorResult = await api.resources.authors.post({
   name: 'George',
   surname: 'Orwell',
-  publisher_id: penguinResult.id
+  publisher: penguinResult.id
 });
 console.log('Created author:', inspect(authorResult));
 
@@ -211,25 +211,25 @@ JSON:API response: {
   },
   links: { self: '/api/publishers/3' }
 }
-Created author: { id: '1', name: 'George', surname: 'Orwell', publisher_id: '1' }
+Created author: { id: '1', name: 'George', surname: 'Orwell', publisher: { id: '1' } }
 All publishers: {
   data: [
-    { id: '1', name: 'Penguin Random House', authors_ids: [ '1' ] },
-    { id: '2', name: 'HarperCollins', authors_ids: [] },
-    { id: '3', name: 'Oxford University Press', authors_ids: [] }
+    { id: '1', name: 'Penguin Random House', authors: [ { id: '1' } ] },
+    { id: '2', name: 'HarperCollins', authors: [] },
+    { id: '3', name: 'Oxford University Press', authors: [] }
   ],
   links: { self: '/api/publishers' }
 }
-Publisher with authors: { id: '1', name: 'Penguin Random House', authors_ids: [ '1' ] }
+Publisher with authors: { id: '1', name: 'Penguin Random House', authors: [ { id: '1' } ] }
 Search results: {
-  data: [ { id: '1', name: 'George', surname: 'Orwell', publisher_id: '1' } ],
+  data: [ { id: '1', name: 'George', surname: 'Orwell', publisher: { id: '1' } } ],
   links: { self: '/api/authors' }
 }
 Updated author: {
   id: '1',
   name: 'George',
   surname: 'Orwell (Eric Blair)',
-  publisher_id: '1'
+  publisher: { id: '1' }
 }
 ```
 

package/docs/index.md

@@ -84,10 +84,10 @@ const knex = knexLib({
 });
 
 // Create API instance
-const api = new Api({ name: 'book-catalog-api', version: '1.0.0' });
+const api = new Api({ name: 'book-catalog-api' });
 
 // Install plugins
-await api.use(RestApiPlugin, { publicBaseUrl: '/api/1.0' }); // Basic REST plugin
+await api.use(RestApiPlugin); // Basic REST plugin - URLs auto-detected
 await api.use(RestApiKnexPlugin, { knex }); // Knex connector
 await api.use(ExpressPlugin, {  mountPath: '/api' }); // Express plugin
 

package/docs/mini-guides/file-uploads-complete.md

@@ -17,7 +17,6 @@ import express from 'express';
 // Create API
 const api = new Api({
   name: 'my-library-api',
-  version: '1.0.0'
 });
 
 // Create storage for different file types