json-rest-api 1.0.10 → 1.0.13

package/.claude/settings.local.json

@@ -55,7 +55,15 @@
       "Bash(npx node:*)",
       "Bash(NODE_ENV=test LOG_LEVEL=debug npm test -- tests/query-limits.test.js)",
       "Bash(NODE_ENV=test LOG_LEVEL=debug node --test tests/query-limits.test.js)",
-      "Bash(LOG_LEVEL=debug node test-debug.js)"
+      "Bash(LOG_LEVEL=debug node test-debug.js)",
+      "WebSearch",
+      "Bash(LOG_LEVEL=debug node --test tests/relationships.test.js)",
+      "Read(///**)",
+      "Bash(LOG_LEVEL=debug node --test tests/nested-includes.test.js)",
+      "Bash(export LOG_LEVEL=debug)",
+      "Read(//home/merc/Development/active/jskit/**)",
+      "Bash(LOG_LEVEL=trace node --test tests/relationships.test.js)",
+      "Bash(LOG_LEVEL=debug timeout 10 node --test tests/relationship-endpoints.test.js)"
     ],
     "deny": []
   }

package/AGENTS.md

@@ -0,0 +1,34 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `index.js` re-exports the public plugins from `plugins/` (REST API core, access, CORS, file, connectors) so new features slot in there.
+- Shared helpers and error types live in `lib/`; reuse or extend these modules before adding new utilities elsewhere.
+- Scenario walkthroughs are under `examples/`, long-form references stay in `docs/`, and development scripts reside in `scripts/`.
+- Tests sit in `tests/` with fixtures at `tests/fixtures/`, helpers in `tests/helpers/`, and `quickTest.js` provides a throwaway API for manual poking.
+
+## Build, Test, and Development Commands
+- `npm test` runs `node --test tests/*.test.js` against the in-memory SQLite fixtures; run it before every push.
+- `node quickTest.js` spins up an in-memory API instance for experimenting with endpoints during development.
+- `npm run docs` rebuilds the static docs via `scripts/run-docs.js` whenever reference prose changes.
+- `npm run sloc` prints a line-count summary to gauge change size before opening a PR.
+
+## Coding Style & Naming Conventions
+- Stay with ESM (`"type": "module"`) and export named symbols only; avoid `default` exports for predictable tree-shaking.
+- Use two-space indentation and keep existing spacing in JSON fixtures and migration files.
+- Name runtime files in lower-kebab case (e.g., `rest-api-knex-plugin.js`) and mirror that pattern for tests like `bulk-operations.test.js`.
+- Keep comments brief and reserved for decisions that are not obvious from the code.
+
+## Testing Guidelines
+- Instantiate the API once per suite following `tests/TEST_TEMPLATE.test.js`, and call `cleanTables()` in `beforeEach` to reset state.
+- Seed data through helpers in `tests/fixtures/api-configs.js`; never invoke `api.addResource` directly in test code.
+- Run suites in strict JSON:API mode (`simplified: false`) unless the scenario explicitly covers the simplified flag.
+- Prefer the shared assertion helpers for response checks to keep expectations consistent.
+
+## Commit & Pull Request Guidelines
+- Use concise, capitalised commit subjects that highlight the affected area (e.g., `Access rules tightened`) and group related changes per commit.
+- Pull requests should include a short summary, linked issue reference, impacted plugins or resources, and `npm test` output or the reason it was skipped.
+- Document externally visible updates with sample payloads or screenshots, and note configuration changes in `docs/` for downstream teams.
+
+## Security & Configuration Tips
+- Keep secrets in local `.env` files; never commit environment-specific strings.
+- When adding connectors or auth flows, review `plugins/core/rest-api-cors-plugin.js`, update optional peers (`express`, `redis`, `socket.io`) if required, and document new toggles in `docs/`.

package/CLAUDE.md

@@ -30,6 +30,24 @@ npm run docs:dev
 ### Project Overview
 JSON REST API is a powerful REST API plugin for hooked-api that provides JSON:API-compliant endpoints. It follows a plugin-based architecture where functionality is composed through plugins that extend the core API capabilities.
 
+### Database-First Design Philosophy
+JSON REST API embraces a **database-first** approach that provides different abstraction levels for different audiences:
+
+**For Backend Developers:**
+- Schema definitions directly map to database columns (e.g., `author_id`, `category_id`)
+- Hooks operate at the database level with access to actual field names via `context.belongsToUpdates`
+- Search schemas can reference exact database columns and table joins
+- Full access to write raw Knex queries when needed
+- No abstraction layers hiding database implementation details
+
+**For API Consumers:**
+- Relationship names abstract away foreign key fields (use `author` instead of `author_id`)
+- Simplified API mode returns clean objects without database implementation details
+- Foreign key fields are automatically filtered from API responses
+- Consistent interface regardless of underlying database structure
+
+This separation ensures backend developers have full control and visibility into database operations while API consumers enjoy a clean, intuitive interface.
+
 ### Core Architecture Components
 
 1. **Plugin System (hooked-api based)**
@@ -50,12 +68,19 @@ JSON REST API is a powerful REST API plugin for hooked-api that provides JSON:AP
    - Each plugin can hook into the request lifecycle for customization
 
 4. **Key Libraries in `plugins/core/lib/`**
-   - `knex-json-api-helpers.js` - Core JSON:API transformations
+   - `url-helpers.js` - Centralized URL generation functions
+   - `knex-json-api-transformers-querying.js` - JSON:API transformations
    - `relationship-processor.js` - Handles relationship updates
    - `payload-validators.js` - Request validation
    - `knex-query-helpers.js` - Database query building
    - `simplified-helpers.js` - Simplified API mode transformations
 
+5. **URL Management**
+   - URLs are automatically generated per-request based on headers
+   - No static configuration needed - detects from `Host`, `X-Forwarded-*` headers
+   - Override capability via `context.urlPrefixOverride` for complex deployments
+   - See `docs/GUIDE/GUIDE_URL_Management.md` for details
+
 ## Testing Guidelines
 
 ### CRITICAL: Test Template Usage

package/CRUSH.md

@@ -0,0 +1,55 @@
+# CRUSH.md - JSON REST API Development Guide
+
+## Development Commands
+```bash
+# Run all tests
+npm test
+
+# Run specific test file
+node --test tests/relationships.test.js
+
+# Run tests with debug logging
+LOG_LEVEL=debug npm test
+
+# Run documentation site
+npm run docs
+```
+
+## Code Style Guidelines
+- **ES Modules**: Use `import/export` syntax (package.json has `"type": "module"`)
+- **File Naming**: kebab-case for files, camelCase for functions/variables
+- **Error Handling**: Use custom error classes from `lib/rest-api-errors.js`
+- **JSON:API Compliance**: All responses must follow JSON:API specification
+- **Async/Await**: Prefer async/await over callbacks/promises
+- **JSDoc Comments**: Document complex functions with @param and @returns
+
+## Testing Rules (CRITICAL)
+- **API Creation**: Only in `before()` hook, never in `beforeEach()`
+- **Resource Definition**: NEVER use `api.addResource()` in test files - define in `tests/fixtures/api-configs.js`
+- **Data Access**: Use API methods (`api.resources.[resource].get/post/query`), never direct DB queries
+- **Context Parameter**: Pass context as SECOND parameter: `api.resources.books.post({inputRecord}, context)`
+- **Cleanup**: Use `cleanTables()` in `beforeEach()` to reset data
+
+## Import Patterns
+```javascript
+// Core imports first
+import { validateRelationships } from './lib/querying-writing/scope-validations.js';
+
+// Hook imports
+import compileResourceSchemas from './rest-api-plugin-hooks/compile-resource-schemas.js';
+
+// Method imports
+import queryMethod from './rest-api-plugin-methods/query.js';
+```
+
+## Error Handling
+- Use `RestApiValidationError` for validation failures
+- Use `RestApiResourceError` for resource-related errors
+- Use `RestApiPayloadError` for malformed payloads
+- Always include descriptive error messages
+
+## JSON:API Helpers
+- Use `createJsonApiDocument()` for creating request payloads
+- Use `createRelationship()` for belongsTo relationships
+- Use `createToManyRelationship()` for hasMany relationships
+- Use `validateJsonApiStructure()` to validate responses

package/README.md

@@ -37,12 +37,12 @@ const knex = knexLib({
 });
 
 // Create API instance
-const api = new Api({ name: 'book-catalog-api', version: '1.0.0', logLevel: 'trace' });
+const api = new Api({ name: 'book-catalog-api', logLevel: 'trace' });
 
 // Install plugins
-await api.use(RestApiPlugin, { publicBaseUrl: '/api' });
+await api.use(RestApiPlugin);
 await api.use(RestApiKnexPlugin, { knex });
-await api.use(ExpressPlugin, {  mountPath: '/api' }); // Added: Express Plugin
+await api.use(ExpressPlugin, { mountPath: '/api' }); // Express connector
 
 
 // Define authors resource, which belongs to a publisher

package/TODO.todo

@@ -1,3 +1,11 @@
+  Potential Enhancements
+
+  1. Provider Priority: Consider adding a "primary_provider" field to handle users who authenticate through multiple providers.
+  2. Field Cleanup: Maybe add a helper to remove provider fields when a user unlinks that provider.
+  3. Migration Safety: The automatic column creation via RestApiKnexPlugin is convenient, but you might want provider plugins to check if their
+  fields already exist before extending.
+
+  
 ☐ Delete "Creating Custom Storage Plugins for JSON REST API", make an op plugin instead.
 ☐ Improve the look of the CSS, especially black and long code fragments, title fonts
 ☐ Check manually that the API is OK 

package/docs/API.md

@@ -139,7 +139,7 @@ All parameters are passed within a single `params` object:
       id: '1',
       title: 'First Article',
       content: 'Article content...',
-      author_id: '10',
+      author: '10',
       author: {
         id: '10',
         name: 'John Doe'
@@ -181,13 +181,13 @@ const result = await api.resources.articles.query({
   queryParams: {
     filters: {
       status: 'published',
-      author_id: '10'
+      author: '10'
     }
   }
 });
 
 // HTTP equivalent
-// GET /articles?filter[status]=published&filter[author_id]=10
+// GET /articles?filter[status]=published&filter[author]=10
 ```
 
 **Query with Sorting and Pagination:**
@@ -325,7 +325,7 @@ const result = await api.resources.[resourceType].get(params, context)
   id: '1',
   title: 'Article Title',
   content: 'Full article content...',
-  author_id: '10',
+  author: '10',
   author: {
     id: '10',
     name: 'John Doe'
@@ -483,7 +483,7 @@ const result = await api.resources.articles.post({
     title: 'New Article',
     content: 'Article content...',
     status: 'draft',
-    author_id: '10'
+    author: '10'
   }
 });
 
@@ -520,8 +520,8 @@ const result = await api.resources.articles.post({
   inputRecord: {
     title: 'New Article',
     content: 'Article content...',
-    author_id: '10',
-    tag_ids: ['1', '2', '3']
+    author: '10',
+    tags: ['1', '2', '3']
   },
   queryParams: {
     include: ['author', 'tags']
@@ -639,7 +639,7 @@ const result = await api.resources.articles.put({
     title: 'Completely New Title',
     content: 'Entirely new content',
     status: 'published',
-    author_id: '10'
+    author: '10'
     // Note: All attributes must be provided
   }
 });
@@ -681,8 +681,8 @@ const result = await api.resources.articles.put({
     title: 'Article Without Author',
     content: 'Content...',
     status: 'draft',
-    author_id: null,  // Remove author
-    tag_ids: []       // Remove all tags
+    author: null,  // Remove author
+    tags: []       // Remove all tags
   }
 });
 ```
@@ -805,8 +805,8 @@ const result = await api.resources.articles.patch({
 const result = await api.resources.articles.patch({
   inputRecord: {
     id: '1',
-    author_id: '30',
-    tag_ids: ['3', '4', '5']
+    author: '30',
+    tags: ['3', '4', '5']
   }
 });
 ```
@@ -1496,7 +1496,7 @@ api.resource('articles').hook('afterSchemaValidate', async (context) => {
 ```javascript
 api.resource('articles').hook('checkDataPermissionsDelete', async (context) => {
   // Only author or admin can delete
-  if (context.auth.userId !== context.existingRecord.author_id && 
+  if (context.auth.userId !== context.existingRecord.relationships?.author?.data?.id && 
       !context.auth.isAdmin) {
     throw new Error('Unauthorized to delete this article');
   }
@@ -1533,7 +1533,7 @@ api.resource('articles').hook('beforeDataQuery', async (context) => {
   if (context.auth.userId && !context.auth.isAdmin) {
     context.storageParams.filters = {
       ...context.storageParams.filters,
-      author_id: context.auth.userId
+      author: context.auth.userId
     };
   }
 });
@@ -1633,7 +1633,6 @@ api.resource('articles').hook('finish', async (context) => {
   context.response.meta = {
     ...context.response.meta,
     generated_at: new Date().toISOString(),
-    api_version: '1.0'
   };
 });
 ```
@@ -1741,13 +1740,13 @@ const result = await api.resources.articles.query({
   queryParams: {
     filters: {
       status: 'published',
-      author_id: '10'
+      author: '10'
     }
   }
 });
 
 // HTTP equivalent
-// GET /articles?filter[status]=published&filter[author_id]=10
+// GET /articles?filter[status]=published&filter[author]=10
 ```
 
 #### Operator-based Filtering
@@ -2234,7 +2233,7 @@ api.addResource({
         type: 'datetime',
         operators: ['gt', 'gte', 'lt', 'lte']
       },
-      author_id: {
+      author: {
         type: 'number',
         operators: ['eq', 'in']
       },

package/docs/COMPARISON.md

@@ -67,8 +67,8 @@ const BookSerializer = new JSONAPISerializer('books', {
 import { Api } from 'hooked-api';
 import { RestApiPlugin, RestApiKnexPlugin } from 'json-rest-api';
 
-const api = new Api({ name: 'bookstore-api', version: '1.0.0' });
-await api.use(RestApiPlugin, { publicBaseUrl: '/api/v1' });
+const api = new Api({ name: 'bookstore-api'});
+await api.use(RestApiPlugin); // URLs auto-detected
 await api.use(RestApiKnexPlugin, { knex });
 
 await api.addResource('books', {
@@ -109,7 +109,7 @@ export class BookEntity {
 import { Api } from 'hooked-api';
 import { RestApiPlugin, ExpressPlugin, SocketIOPlugin } from 'json-rest-api';
 
-const api = new Api({ name: 'books-api', version: '1.0.0' });
+const api = new Api({ name: 'books-api' });
 await api.use(RestApiPlugin);
 await api.use(ExpressPlugin);    // HTTP transport
 await api.use(SocketIOPlugin);   // WebSocket transport
@@ -173,9 +173,9 @@ const response = await fetch('/api/books', {
 // Simplified mode (for internal/programmatic use)
 const book = await api.resources.books.post({
   title: 'My Book',
-  author_id: 1
+  author: 1
 });
-// Returns: { id: '1', title: 'My Book', author_id: 1 }
+// Returns: { id: '1', title: 'My Book', author: { id: 1 } }
 
 // Configure both modes simultaneously
 await api.use(RestApiPlugin, {
@@ -201,10 +201,10 @@ import {
   SocketIOPlugin
 } from 'json-rest-api';
 
-const api = new Api({ name: 'full-featured-api', version: '1.0.0' });
+const api = new Api({ name: 'full-featured-api' });
 
 // Core functionality
-await api.use(RestApiPlugin, { publicBaseUrl: '/api/v1' });
+await api.use(RestApiPlugin); // URLs auto-detected
 await api.use(RestApiKnexPlugin, { knex: connection });
 
 // Transport layer
@@ -264,7 +264,7 @@ await api.addResource('comments', {
 // Parent resources define reverse relationship
 await api.addResource('posts', {
   relationships: {
-    comments: { hasMany: 'comments', via: 'commentable' }
+    comments: { type: 'hasMany', target: 'comments', via: 'commentable' }
   }
 });
 
@@ -290,20 +290,25 @@ Automatic optimization that competitors lack:
 // Define resources with nested relationships
 await api.addResource('countries', {
   relationships: {
-    publishers: { hasMany: 'publishers', foreignKey: 'country_id' }
+    publishers: { type: 'hasMany', target: 'publishers', foreignKey: 'country_id' }
   }
 });
 
 await api.addResource('publishers', {
   relationships: {
-    books: { hasMany: 'books', foreignKey: 'publisher_id' },
+    books: { type: 'hasMany', target: 'books', foreignKey: 'publisher_id' },
     country: { belongsTo: 'countries' }
   }
 });
 
 await api.addResource('books', {
   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'
+    },
     publisher: { belongsTo: 'publishers' }
   }
 });
@@ -362,7 +367,7 @@ app.get('/books', async (req, res) => {
 import { Api } from 'hooked-api';
 import { RestApiPlugin, RestApiKnexPlugin, ExpressPlugin } from 'json-rest-api';
 
-const api = new Api({ name: 'books-api', version: '1.0.0' });
+const api = new Api({ name: 'books-api' });
 await api.use(RestApiPlugin);
 await api.use(RestApiKnexPlugin, { knex: db });
 await api.use(ExpressPlugin, { mountPath: '/api' });
@@ -398,7 +403,7 @@ export class BooksController {
 import { Api } from 'hooked-api';
 import { RestApiPlugin, RestApiKnexPlugin } from 'json-rest-api';
 
-const api = new Api({ name: 'books-api', version: '1.0.0' });
+const api = new Api({ name: 'books-api' });
 await api.use(RestApiPlugin);
 await api.use(RestApiKnexPlugin, { knex });
 

package/docs/GUIDE/GUIDE_1_Initial_Setup.md

@@ -41,10 +41,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' });
+await api.use(RestApiPlugin);
 await api.use(RestApiKnexPlugin, { knex });
 
 // Define schemas for our book catalog system
@@ -56,8 +56,8 @@ await api.addResource('countries', {
     code: { type: 'string', max: 2, unique: true, search: true }, // ISO country code
   },
   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' }
   },
 });
 await api.resources.countries.createKnexTable()
@@ -89,7 +89,6 @@ To change loglevels, pass a logLevel option to the API:
 ```javascript
 const api = new Api({ 
   name: 'book-catalog-api', 
-  version: '1.0.0',
   logLevel: 'warn'  // Only show warnings and errors
 });
 ```
@@ -220,9 +219,9 @@ console.log('Created Country:', inspect(countryUs));
 //     type: 'countries',
 //     id: '1',
 //     attributes: { name: 'United States', code: 'US' },
-//     links: { self: '/api/1.0/countries/1' }
+//     links: { self: '/api/countries/1' }
 //   },
-//   links: { self: '/api/1.0/countries/1' }
+//   links: { self: '/api/countries/1' }
 // }
 
 // Fetch a country by ID (non-simplified mode)
@@ -237,13 +236,13 @@ console.log('Refetched Country:', inspect(countryUsRefetched));
 //     type: 'countries',
 //     id: '1',
 //     attributes: { name: 'United States', code: 'US' },
-//     links: { self: '/api/1.0/countries/1' }
+//     links: { self: '/api/countries/1' }
 //   },
-//   links: { self: '/api/1.0/countries/1' }
+//   links: { self: '/api/countries/1' }
 // }
 ```
 
-(Note that the full JSON:API record includes links to resources, which use `publicBaseUrl` set in when `use()`ing the `json-rest-api` plugin.)
+(Note that the full JSON:API record includes links to resources, which are automatically generated based on the request headers.)
 
 As you can see, when `simplified: false` is used:
 
@@ -348,7 +347,7 @@ Here's how these settings work:
 
 ```javascript
 // Example 1: Using defaults
-const api = new Api({ name: 'api', version: '1.0.0' });
+const api = new Api({ name: 'api' });
 await api.use(RestApiPlugin); 
 // Default: returnRecordApi='full', returnRecordTransport='no'
 
@@ -418,9 +417,9 @@ console.log('Full JSON:API response:', inspect(fullJsonApi));
 //     type: 'countries',
 //     id: '4',
 //     attributes: { name: 'France', code: 'FR' },
-//     links: { self: '/api/1.0/countries/4' }
+//     links: { self: '/api/countries/4' }
 //   },
-//   links: { self: '/api/1.0/countries/4' }
+//   links: { self: '/api/countries/4' }
 // }
 
 // Non-simplified mode with minimal return
@@ -542,12 +541,12 @@ 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' });
+await api.use(RestApiPlugin);
 await api.use(RestApiKnexPlugin, { knex });
-await api.use(ExpressPlugin, {  mountPath: '/api' }); // Added: Express Plugin
+await api.use(ExpressPlugin, { mountPath: '/api' }); // Added: Express Plugin
 
 // Countries table
 await api.addResource('countries', {
@@ -757,12 +756,11 @@ Keep-Alive: timeout=5
 When passing a parameter, `rest-api-plugin` normalises them (when needed) and stores them into plugin variables. This means that these two ways of defining `returnRecordApi` is identical:
 
 ```javascript
-await api.use(RestApiPlugin, { publicBaseUrl: '/api/1.0',  returnRecordTransport: 'minimal'});
+await api.use(RestApiPlugin, { returnRecordTransport: 'minimal' });
 
 // ...or...
 
 await api.use(RestApiPlugin, { 
-  publicBaseUrl: '/api/1.0', 
   vars: {
     returnRecordTransport: 'minimal'
   }
@@ -776,7 +774,6 @@ Here is a full list of parameters and their respective variables:
 | `queryDefaultLimit` | `vars.queryDefaultLimit` | `25` | Default number of records returned in query results | ✓ |
 | `queryMaxLimit` | `vars.queryMaxLimit` | `100` | Maximum allowed limit for query results | ✓ |
 | `includeDepthLimit` | `vars.includeDepthLimit` | `3` | Maximum depth for nested relationship includes | ✓ |
-| `publicBaseUrl` | `vars.publicBaseUrl` | `''` | Base URL for generated links (e.g., `https://api.example.com/v1`) | ✓ |
 | `enablePaginationCounts` | `vars.enablePaginationCounts` | `true` | Whether to include total count in pagination metadata | ✓ |
 | `simplifiedApi` | `vars.simplifiedApi` | `true` | Use simplified format for programmatic API calls | ✓ |
 | `simplifiedTransport` | `vars.simplifiedTransport` | `false` | Use simplified format for HTTP/REST endpoints | ✓ |
@@ -832,7 +829,7 @@ When you install the REST API plugins, the following helpers are added to `api.h
   try {
     // Use transaction in multiple operations
     await api.resources.countries.post({ name: 'France', code: 'FR' }, { transaction: trx });
-    await api.resources.publishers.post({ name: 'French Press', country_id: 1 }, { transaction: trx });
+    await api.resources.publishers.post({ name: 'French Press', country: 1 }, { transaction: trx });
     await trx.commit();
   } catch (error) {
     await trx.rollback();
@@ -938,7 +935,6 @@ Each resource (added via `api.addResource()`) gets these methods automatically:
 
 - **`api.rest.registerFileDetector(detector)`** - Registers file upload detectors (requires FileHandlingPlugin)
 - **`api.rest.fileDetectors`** - Registry of file detectors for handling uploads
-- **`api.knex.helpers.crossTableSearch`** - Utilities for searching across related tables
 
 ## Summary
 

package/docs/GUIDE/GUIDE_2_1_The_Starting_Point.md

@@ -20,10 +20,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' });
+await api.use(RestApiPlugin); // URLs auto-detected from request headers
 await api.use(RestApiKnexPlugin, { knex });
 await api.use(ExpressPlugin, {  mountPath: '/api' }); // Added: Express Plugin
 
@@ -52,6 +52,37 @@ This will ensure that each example has a fresh start.
 
 Each example will be introduced programmatically first, and then via HTTP. The HTTP calls will be run assuming that the API calls (and any data created with them) stay. The use of the in-memory database will be assumed, which means that the data will start afresh each time.
 
+## Database-First Design Philosophy
+
+JSON REST API follows a **database-first** approach, providing different levels of abstraction for different audiences:
+
+### For Backend Developers (Schema Definition, Hooks, and Internal Logic)
+
+When defining schemas and writing hooks, you work directly with database reality:
+- Schema fields map directly to database columns (`author_id`, `category_id`, `commentable_type`)
+- Hooks receive actual database field names in `context.belongsToUpdates`
+- Search schemas can reference exact database columns and table structures
+- Full access to write raw Knex queries when needed
+
+This direct approach ensures backend developers have complete control and visibility into database operations.
+
+### For API Consumers (External Interface)
+
+The API layer provides a clean abstraction that shields consumers from database implementation details:
+- Relationships use semantic names (`author`, `category`) instead of foreign key fields
+- Foreign key fields (`author_id`, `category_id`) are automatically filtered from API responses
+- Polymorphic type/id fields (`commentable_type`, `commentable_id`) are hidden behind relationship objects
+- Simplified mode returns intuitive objects without exposing database structure
+
+### Why This Matters for Relationships
+
+This abstraction is particularly important for **belongsTo** and **polymorphic** relationships, where foreign key fields would otherwise be exposed in API responses. The system ensures that:
+- Input: Consumers provide relationships using clean names (`author: 123`)
+- Output: Responses return relationship objects (`author: { id: '123' }`)
+- Internal: Hooks and database operations work with actual columns (`author_id`)
+
+This design provides the best of both worlds: backend developers get full database access for powerful implementations, while API consumers enjoy a clean, intuitive interface.
+
 ---
 
 [Back to Guide](./README.md) | [Next: 2.2 Manipulating and searching tables with no relationships](./GUIDE_2_2_Manipulating_And_Searching_Tables.md)