json-rest-api 1.0.10 → 1.0.13

package/docs/GUIDE/GUIDE_2_5_HasMany_Polymorphic.md

@@ -17,8 +17,8 @@ await api.addResource('publishers', {
     name: { type: 'string', required: true, max: 255, search: true, indexed: true},
   },
   relationships: {
-    authors: { hasMany: 'authors', foreignKey: 'publisher_id' },
-    reviews: { hasMany: 'reviews', via: 'reviewable' } // Polymorphic relationship
+    authors: { type: 'hasMany', target: 'authors', foreignKey: 'publisher_id' },
+    reviews: { type: 'hasMany', target: 'reviews', via: 'reviewable' } // Polymorphic relationship
   },
 });
 await api.resources.publishers.createKnexTable();
@@ -31,7 +31,7 @@ await api.addResource('authors', {
     publisher_id: { type: 'id', belongsTo: 'publishers', as: 'publisher', nullable: true }
   },
   relationships: {
-    reviews: { hasMany: 'reviews', via: 'reviewable' } // Polymorphic relationship
+    reviews: { type: 'hasMany', target: 'reviews', via: 'reviewable' } // Polymorphic relationship
   },
 });
 await api.resources.authors.createKnexTable();
@@ -78,10 +78,26 @@ So when the parent defines the relationship, they just have to mention `reviewab
 
 ```javascript
   relationships: {
-    reviews: { hasMany: 'reviews', via: 'reviewable' } // Polymorphic relationship
+    reviews: { type: 'hasMany', target: 'reviews', via: 'reviewable' } // Polymorphic relationship
   },
 ```
 
+## Field Visibility and Polymorphic Relationships
+
+Polymorphic relationships are a prime example of json-rest-api's database-first philosophy and field abstraction:
+
+**Database Reality (What Backend Developers Define):**
+- Schema includes `reviewable_type` and `reviewable_id` fields
+- These are actual database columns that store the polymorphic relationship
+- Hooks receive these field names in `context.belongsToUpdates`
+
+**API Abstraction (What Consumers See):**
+- Input: Use `reviewable` relationship object instead of type/id fields
+- Output: Returns `reviewable: { id: '123', _type: 'authors' }` 
+- The `reviewable_type` and `reviewable_id` fields are hidden from API responses
+
+This ensures API consumers work with clean relationship objects while backend developers maintain full control over the database implementation.
+
 `json-rest-api` provides flexibility in how you provide data for polymorphic relationships when creating new records, depending on whether you're using the simplified API mode (default for programmatic calls) or the strict JSON:API format.
 
 Here is how to add reviews, both in simplified and non-simplified mode:
@@ -96,15 +112,13 @@ const germanAuthor_ns = await api.resources.authors.post({ name: 'Johann (NS)',
 const review1_simplified = await api.resources.reviews.post({
   rating: 4,
   comment: 'Great German author! (Simplified)',
-  reviewable_type: 'authors',
-  reviewable_id: germanAuthor_ns.id
+  reviewable: { id: germanAuthor_ns.id, _type: 'authors' }
 });
 
 const review2_simplified = await api.resources.reviews.post({
   rating: 1,
   comment: 'I do not enjoy their books',
-  reviewable_type: 'publishers',
-  reviewable_id: frenchPublisher_ns.id 
+  reviewable: { id: frenchPublisher_ns.id, _type: 'publishers' }
 });
 
 
@@ -151,8 +165,8 @@ const frenchAuthor1_with_reviews_non_simplified = await api.resources.authors.ge
 const french_authors_simplified = await api.resources.authors.query({});
 // HTTP: GET /api/authors
 // Returns (simplified): [
-//   { id: '1', name: 'Victor Hugo', publisher_id: '1' },
-//   { id: '2', name: 'Alexandre Dumas', publisher_id: '1' }
+//   { id: '1', name: 'Victor Hugo', surname: 'Hugo', publisher: { id: '1' } },
+//   { id: '2', name: 'Alexandre Dumas', surname: 'Dumas', publisher: { id: '1' } }
 // ]
 
 const french_authors_non_simplified = await api.resources.authors.query({simplified: false });
@@ -199,26 +213,26 @@ Added Publisher Review (non-Simplified): {
     type: 'reviews',
     id: '3',
     attributes: { rating: 3, comment: 'Decent publisher, some good titles (NS).' },
-    links: { self: '/api/1.0/reviews/3' }
+    links: { self: '/api/reviews/3' }
   },
-  links: { self: '/api/1.0/reviews/3' }
+  links: { self: '/api/reviews/3' }
 }
 Added Author Review (non-Simplified): {
   data: {
     type: 'reviews',
     id: '4',
     attributes: { rating: 5, comment: 'Hugo is a master storyteller! (NS)' },
-    links: { self: '/api/1.0/reviews/4' }
+    links: { self: '/api/reviews/4' }
   },
-  links: { self: '/api/1.0/reviews/4' }
+  links: { self: '/api/reviews/4' }
 }
 French author with the newly added reviews (simplified):
 {
   id: '1',
   name: 'Victor (NS)',
   surname: 'Hugo (NS)',
-  reviews_ids: [ '4' ],
-  publisher_id: '1'
+  reviews: [ { id: '4' } ],
+  publisher: { id: '1' }
 }
 French author with the newly added reviews (non-simplified):
 {
@@ -231,14 +245,14 @@ French author with the newly added reviews (non-simplified):
       publisher: {
         data: { type: 'publishers', id: '1' },
         links: {
-          self: '/api/1.0/authors/1/relationships/publisher',
-          related: '/api/1.0/authors/1/publisher'
+          self: '/api/authors/1/relationships/publisher',
+          related: '/api/authors/1/publisher'
         }
       }
     },
-    links: { self: '/api/1.0/authors/1' }
+    links: { self: '/api/authors/1' }
   },
-  links: { self: '/api/1.0/authors/1' }
+  links: { self: '/api/authors/1' }
 }
 French authors with the newly added reviews (simplified):
 [
@@ -246,15 +260,15 @@ French authors with the newly added reviews (simplified):
     id: '1',
     name: 'Victor (NS)',
     surname: 'Hugo (NS)',
-    reviews_ids: [ '4' ],
-    publisher_id: '1'
+    reviews: [ { id: '4' } ],
+    publisher: { id: '1' }
   },
   {
     id: '2',
     name: 'Johann (NS)',
     surname: 'Goethe (NS)',
-    reviews_ids: [ '1' ],
-    publisher_id: '2'
+    reviews: [ { id: '1' } ],
+    publisher: { id: '2' }
   }
 ]
 French authors with the newly added reviews (non-simplified):
@@ -269,12 +283,12 @@ French authors with the newly added reviews (non-simplified):
         publisher: {
           data: { type: 'publishers', id: '1' },
           links: {
-            self: '/api/1.0/authors/1/relationships/publisher',
-            related: '/api/1.0/authors/1/publisher'
+            self: '/api/authors/1/relationships/publisher',
+            related: '/api/authors/1/publisher'
           }
         }
       },
-      links: { self: '/api/1.0/authors/1' }
+      links: { self: '/api/authors/1' }
     },
     {
       type: 'authors',
@@ -285,15 +299,15 @@ French authors with the newly added reviews (non-simplified):
         publisher: {
           data: { type: 'publishers', id: '2' },
           links: {
-            self: '/api/1.0/authors/2/relationships/publisher',
-            related: '/api/1.0/authors/2/publisher'
+            self: '/api/authors/2/relationships/publisher',
+            related: '/api/authors/2/publisher'
           }
         }
       },
-      links: { self: '/api/1.0/authors/2' }
+      links: { self: '/api/authors/2' }
     }
   ],
-  links: { self: '/api/1.0/authors' }
+  links: { self: '/api/authors' }
 }
 ```
 
@@ -314,10 +328,10 @@ const frenchAuthor1_with_reviews_and_includes_non_simplified = await api.resourc
 const french_authors_with_includes_simplified = await api.resources.authors.query({queryParams: { include: ['reviews'] } });
 // HTTP: GET /api/authors?include=reviews
 // Returns (simplified): [
-//   { id: '1', name: 'Victor Hugo', publisher_id: '1', 
-//     reviews: [{ id: '2', comment: 'A master storyteller', rating: 5, reviewable_type: 'authors', reviewable_id: '1' }]
+//   { id: '1', name: 'Victor Hugo', surname: 'Hugo', publisher: { id: '1' }, 
+//     reviews: [{ id: '2', comment: 'A master storyteller', rating: 5, reviewable: { id: '1', _type: 'authors' } }]
 //   },
-//   { id: '2', name: 'Alexandre Dumas', publisher_id: '1', reviews: [] }
+//   { id: '2', name: 'Alexandre Dumas', surname: 'Dumas', publisher: { id: '1' }, reviews: [] }
 // ]
 
 const french_authors_with_includes_non_simplified = await api.resources.authors.query({queryParams: { include: ['reviews'] }, simplified: false });
@@ -363,11 +377,10 @@ French author with the newly added reviews (simplified):
       id: '4',
       rating: 5,
       comment: 'Hugo is a master storyteller! (NS)',
-      reviewable_type: 'authors',
-      reviewable_id: '1'
+      reviewable: { id: '1', _type: 'authors' }
     }
   ],
-  publisher_id: '1'
+  publisher: { id: '1' }
 }
 French author with the newly added reviews (non-simplified):
 {
@@ -379,19 +392,19 @@ French author with the newly added reviews (non-simplified):
       reviews: {
         data: [ { type: 'reviews', id: '4' } ],
         links: {
-          self: '/api/1.0/authors/1/relationships/reviews',
-          related: '/api/1.0/authors/1/reviews'
+          self: '/api/authors/1/relationships/reviews',
+          related: '/api/authors/1/reviews'
         }
       },
       publisher: {
         data: { type: 'publishers', id: '1' },
         links: {
-          self: '/api/1.0/authors/1/relationships/publisher',
-          related: '/api/1.0/authors/1/publisher'
+          self: '/api/authors/1/relationships/publisher',
+          related: '/api/authors/1/publisher'
         }
       }
     },
-    links: { self: '/api/1.0/authors/1' }
+    links: { self: '/api/authors/1' }
   },
   included: [
     {
@@ -399,10 +412,10 @@ French author with the newly added reviews (non-simplified):
       id: '4',
       attributes: { rating: 5, comment: 'Hugo is a master storyteller! (NS)' },
       relationships: { reviewable: { data: { type: 'authors', id: '1' } } },
-      links: { self: '/api/1.0/reviews/4' }
+      links: { self: '/api/reviews/4' }
     }
   ],
-  links: { self: '/api/1.0/authors/1' }
+  links: { self: '/api/authors/1' }
 }
 French authors with the newly added reviews (simplified):
 [
@@ -416,27 +429,24 @@ French authors with the newly added reviews (simplified):
         id: '4',
         rating: 5,
         comment: 'Hugo is a master storyteller! (NS)',
-        reviewable_type: 'authors',
-        reviewable_id: '1'
+        reviewable: { id: '1', _type: 'authors' }
       }
     ],
-    publisher_id: '1'
+    publisher: { id: '1' }
   },
   {
     id: '2',
     name: 'Johann (NS)',
     surname: 'Goethe (NS)',
-    reviews_ids: [ '1' ],
     reviews: [
       {
         id: '1',
         rating: 4,
         comment: 'Great German author! (Simplified)',
-        reviewable_type: 'authors',
-        reviewable_id: '2'
+        reviewable: { id: '2', _type: 'authors' }
       }
     ],
-    publisher_id: '2'
+    publisher: { id: '2' }
   }
 ]
 French authors with the newly added reviews (non-simplified):
@@ -450,19 +460,19 @@ French authors with the newly added reviews (non-simplified):
         reviews: {
           data: [ { type: 'reviews', id: '4' } ],
           links: {
-            self: '/api/1.0/authors/1/relationships/reviews',
-            related: '/api/1.0/authors/1/reviews'
+            self: '/api/authors/1/relationships/reviews',
+            related: '/api/authors/1/reviews'
           }
         },
         publisher: {
           data: { type: 'publishers', id: '1' },
           links: {
-            self: '/api/1.0/authors/1/relationships/publisher',
-            related: '/api/1.0/authors/1/publisher'
+            self: '/api/authors/1/relationships/publisher',
+            related: '/api/authors/1/publisher'
           }
         }
       },
-      links: { self: '/api/1.0/authors/1' }
+      links: { self: '/api/authors/1' }
     },
     {
       type: 'authors',
@@ -472,19 +482,19 @@ French authors with the newly added reviews (non-simplified):
         reviews: {
           data: [ { type: 'reviews', id: '1' } ],
           links: {
-            self: '/api/1.0/authors/2/relationships/reviews',
-            related: '/api/1.0/authors/2/reviews'
+            self: '/api/authors/2/relationships/reviews',
+            related: '/api/authors/2/reviews'
           }
         },
         publisher: {
           data: { type: 'publishers', id: '2' },
           links: {
-            self: '/api/1.0/authors/2/relationships/publisher',
-            related: '/api/1.0/authors/2/publisher'
+            self: '/api/authors/2/relationships/publisher',
+            related: '/api/authors/2/publisher'
           }
         }
       },
-      links: { self: '/api/1.0/authors/2' }
+      links: { self: '/api/authors/2' }
     }
   ],
   included: [
@@ -493,17 +503,17 @@ French authors with the newly added reviews (non-simplified):
       id: '4',
       attributes: { rating: 5, comment: 'Hugo is a master storyteller! (NS)' },
       relationships: { reviewable: { data: { type: 'authors', id: '1' } } },
-      links: { self: '/api/1.0/reviews/4' }
+      links: { self: '/api/reviews/4' }
     },
     {
       type: 'reviews',
       id: '1',
       attributes: { rating: 4, comment: 'Great German author! (Simplified)' },
       relationships: { reviewable: { data: { type: 'authors', id: '2' } } },
-      links: { self: '/api/1.0/reviews/1' }
+      links: { self: '/api/reviews/1' }
     }
   ],
-  links: { self: '/api/1.0/authors?include=reviews' }
+  links: { self: '/api/authors?include=reviews' }
 }
 ```
 
@@ -535,8 +545,8 @@ await api.addResource('publishers', {
     name: { type: 'string', required: true, max: 255, search: true, indexed: true},
   },
   relationships: {
-    authors: { hasMany: 'authors', foreignKey: 'publisher_id' }, // Regular one-to-many
-    reviews: { hasMany: 'reviews', via: 'reviewable' } // Polymorphic one-to-many
+    authors: { type: 'hasMany', target: 'authors', foreignKey: 'publisher_id' }, // Regular one-to-many
+    reviews: { type: 'hasMany', target: 'reviews', via: 'reviewable' } // Polymorphic one-to-many
   },
   searchSchema: {
     // Search publishers by their review fields (reverse polymorphic search)
@@ -563,7 +573,7 @@ await api.addResource('authors', {
     publisher_id: { type: 'id', belongsTo: 'publishers', as: 'publisher', nullable: true }
   },
   relationships: {
-    reviews: { hasMany: 'reviews', via: 'reviewable' } // Polymorphic one-to-many
+    reviews: { type: 'hasMany', target: 'reviews', via: 'reviewable' } // Polymorphic one-to-many
   },
   searchSchema: {
     // Regular search fields
@@ -666,7 +676,7 @@ reviewComment: {
 }
 
 // In relationships:
-reviews: { hasMany: 'reviews', via: 'reviewable' }  // Polymorphic relationship
+reviews: { type: 'hasMany', target: 'reviews', via: 'reviewable' }  // Polymorphic relationship
 ```
 
 This uses the `via` property to indicate a polymorphic hasMany relationship. The system automatically adds the polymorphic constraints:
@@ -682,19 +692,26 @@ With the same data, run these queries:
 // This searches across BOTH publishers and authors tables based on reviewable_type
 const reviews_filtered_simplified = await api.resources.reviews.query({ queryParams: { filters: {reviewableName: 'Victor'} }})
 // HTTP: GET /api/reviews?filter[reviewableName]=Victor
-// Returns: [{ id: '2', comment: 'A master storyteller', rating: 5, reviewable_type: 'authors', reviewable_id: '1' }]
+// Returns: [{ id: '2', comment: 'A master storyteller', rating: 5, reviewable: { id: '1', _type: 'authors' } }]
 
 const reviews_filtered_non_simplified = await api.resources.reviews.query({queryParams: { filters: {reviewableName: 'Victor'} }, simplified: false })
 // HTTP: GET /api/reviews?filter[reviewableName]=Victor
 // Returns (JSON:API): {
-//   data: [{ type: 'reviews', id: '2', attributes: { comment: 'A master storyteller', rating: 5, reviewable_type: 'authors', reviewable_id: '1' } }]
+//   data: [{ 
+//     type: 'reviews', 
+//     id: '2', 
+//     attributes: { comment: 'A master storyteller', rating: 5 },
+//     relationships: {
+//       reviewable: { data: { type: 'authors', id: '1' } }
+//     }
+//   }]
 // }
 
 // 2. Reverse polymorphic search: Find parents (authors) by their children's (reviews) fields
 // This uses a polymorphic JOIN: reviews.reviewable_type = 'authors' AND reviews.reviewable_id = authors.id
 const authors_filtered_simplified = await api.resources.authors.query({queryParams: { filters: {reviewComment: 'storyteller'} }})
 // HTTP: GET /api/authors?filter[reviewComment]=storyteller
-// Returns: [{ id: '1', name: 'Victor Hugo', publisher_id: '1' }]
+// Returns: [{ id: '1', name: 'Victor Hugo', surname: 'Hugo', publisher: { id: '1' } }]
 
 const authors_filtered_non_simplified = await api.resources.authors.query({queryParams: { filters: {reviewComment: 'storyteller'} }, simplified: false })
 // HTTP: GET /api/authors?filter[reviewComment]=storyteller
@@ -706,7 +723,7 @@ const authors_filtered_non_simplified = await api.resources.authors.query({query
 // This uses a polymorphic JOIN: reviews.reviewable_type = 'publishers' AND reviews.reviewable_id = publishers.id
 const publishers_filtered_simplified = await api.resources.publishers.query({queryParams: { filters: {reviewComment: 'enjoy'} }})
 // HTTP: GET /api/publishers?filter[reviewComment]=enjoy
-// Returns: [{ id: '1', name: 'French Books Inc.', country_id: '1' }]
+// Returns: [{ id: '1', name: 'French Books Inc.' }]
 
 const publishers_filtered_non_simplified = await api.resources.publishers.query({queryParams: { filters: {reviewComment: 'enjoy'} }, simplified: false })
 // HTTP: GET /api/publishers?filter[reviewComment]=enjoy
@@ -741,8 +758,7 @@ Reviews FILTERED (simplified):
       id: '4',
       rating: 5,
       comment: 'Hugo is a master storyteller! (NS)',
-      reviewable_type: 'authors',
-      reviewable_id: '1'
+      reviewable: { id: '1', _type: 'authors' }
     }
   ],
   meta: {...},
@@ -759,15 +775,15 @@ Reviews FILTERED (non-simplified):
         reviewable: {
           data: { type: 'authors', id: '1' },
           links: {
-            self: '/api/1.0/reviews/4/relationships/reviewable',
-            related: '/api/1.0/reviews/4/reviewable'
+            self: '/api/reviews/4/relationships/reviewable',
+            related: '/api/reviews/4/reviewable'
           }
         }
       },
-      links: { self: '/api/1.0/reviews/4' }
+      links: { self: '/api/reviews/4' }
     }
   ],
-  links: { self: '/api/1.0/reviews?filters[reviewableName]=Victor' }
+  links: { self: '/api/reviews?filters[reviewableName]=Victor' }
 }
 Authors FILTERED (simplified):
 {
@@ -776,8 +792,8 @@ Authors FILTERED (simplified):
       id: '1',
       name: 'Victor (NS)',
       surname: 'Hugo (NS)',
-      reviews_ids: [ '4' ],
-      publisher_id: '1'
+      reviews: [ { id: '4' } ],
+      publisher: { id: '1' }
     }
   ],
   meta: {...},
@@ -795,15 +811,15 @@ Authors FILTERED (non-simplified):
         publisher: {
           data: { type: 'publishers', id: '1' },
           links: {
-            self: '/api/1.0/authors/1/relationships/publisher',
-            related: '/api/1.0/authors/1/publisher'
+            self: '/api/authors/1/relationships/publisher',
+            related: '/api/authors/1/publisher'
           }
         }
       },
-      links: { self: '/api/1.0/authors/1' }
+      links: { self: '/api/authors/1' }
     }
   ],
-  links: { self: '/api/1.0/authors?filters[reviewComment]=storyteller' }
+  links: { self: '/api/authors?filters[reviewComment]=storyteller' }
 }
 Publishers FILTERED (simplified):
 {
@@ -834,10 +850,10 @@ Publishers FILTERED (non-simplified):
           ]
         }
       },
-      links: { self: '/api/1.0/publishers/1' }
+      links: { self: '/api/publishers/1' }
     }
   ],
-  links: { self: '/api/1.0/publishers?filters[reviewComment]=enjoy' }
+  links: { self: '/api/publishers?filters[reviewComment]=enjoy' }
 }
 ```
 
@@ -879,4 +895,4 @@ The polymorphic search seamlessly handles the fact that reviews can belong to di
 
 ---
 
-[Previous: 2.4 hasMany records](./GUIDE_2_4_HasMany_Records.md) | [Back to Guide](./README.md) | [Next: 2.6 Many to many (hasMany with through records)](./GUIDE_2_6_Many_To_Many.md)
+[Previous: 2.4 hasMany records](./GUIDE_2_4_HasMany_Records.md) | [Back to Guide](./README.md) | [Next: 2.6 Many to Many Relationships](./GUIDE_2_6_Many_To_Many.md)