json-rest-api 1.0.10 → 1.0.13

package/docs/GUIDE/GUIDE_2_6_Many_To_Many.md

@@ -1,4 +1,4 @@
-# 2.6 Many to many (hasMany with through records)
+# 2.6 Many to Many Relationships
 
 Many-to-many relationships connect two resources through a pivot/junction table. For example, books can have multiple authors, and authors can write multiple books. This relationship is managed through a `book_authors` table that stores the connections.
 
@@ -16,7 +16,7 @@ await api.addResource('books', {
   },
   relationships: {
     authors: { 
-      hasMany: 'authors',
+      type: 'manyToMany',
       through: 'book_authors',  // The pivot table
       foreignKey: 'book_id',    // Column in pivot table pointing to books
       otherKey: 'author_id'     // Column in pivot table pointing to authors
@@ -44,7 +44,7 @@ await api.addResource('authors', {
   },
   relationships: {
     books: { 
-      hasMany: 'books',
+      type: 'manyToMany',
       through: 'book_authors',  // Same pivot table
       foreignKey: 'author_id',  // Column in pivot table pointing to authors
       otherKey: 'book_id'      // Column in pivot table pointing to books
@@ -79,7 +79,10 @@ await api.addResource('book_authors', {
 await api.resources.book_authors.createKnexTable();
 ```
 
-The key difference from regular hasMany relationships is the `through` property, which specifies the pivot table. Both `foreignKey` and `otherKey` are mandatory for many-to-many relationships.
+The `manyToMany` relationship type requires the following properties:
+- `through`: The pivot table name
+- `foreignKey`: The column in the pivot table pointing to the current resource
+- `otherKey`: The column in the pivot table pointing to the related resource
 
 Now let's create some data and explore how to work with many-to-many relationships:
 
@@ -234,9 +237,9 @@ Book without includes (non-simplified):
         ]
       }
     },
-    links: { self: '/api/1.0/books/1' }
+    links: { self: '/api/books/1' }
   },
-  links: { self: '/api/1.0/books/1' }
+  links: { self: '/api/books/1' }
 }
 ```
 
@@ -312,12 +315,12 @@ Book with authors (non-simplified): {
       authors: {
         data: [ { type: 'authors', id: '1' }, { type: 'authors', id: '2' } ],
         links: {
-          self: '/api/1.0/books/1/relationships/authors',
-          related: '/api/1.0/books/1/authors'
+          self: '/api/books/1/relationships/authors',
+          related: '/api/books/1/authors'
         }
       }
     },
-    links: { self: '/api/1.0/books/1' }
+    links: { self: '/api/books/1' }
   },
   included: [
     {
@@ -329,7 +332,7 @@ Book with authors (non-simplified): {
         bio: 'British author of fiction, horror, and fantasy'
       },
       relationships: { books: { data: [] } },
-      links: { self: '/api/1.0/authors/1' }
+      links: { self: '/api/authors/1' }
     },
     {
       type: 'authors',
@@ -340,10 +343,10 @@ Book with authors (non-simplified): {
         bio: 'English humorist and fantasy author'
       },
       relationships: { books: { data: [] } },
-      links: { self: '/api/1.0/authors/2' }
+      links: { self: '/api/authors/2' }
     }
   ],
-  links: { self: '/api/1.0/books/1' }
+  links: { self: '/api/books/1' }
 }
 Books with authors (simplified): {
   data: [
@@ -403,7 +406,7 @@ Books with authors (simplified): {
       ]
     }
   ],
-  links: { self: '/api/1.0/books?include=authors' }
+  links: { self: '/api/books?include=authors' }
 }
 Books with authors (non-simplified): {
   data: [
@@ -422,12 +425,12 @@ Books with authors (non-simplified): {
             { type: 'authors', id: '2' }
           ],
           links: {
-            self: '/api/1.0/books/1/relationships/authors',
-            related: '/api/1.0/books/1/authors'
+            self: '/api/books/1/relationships/authors',
+            related: '/api/books/1/authors'
           }
         }
       },
-      links: { self: '/api/1.0/books/1' }
+      links: { self: '/api/books/1' }
     },
     {
       type: 'books',
@@ -441,12 +444,12 @@ Books with authors (non-simplified): {
         authors: {
           data: [ { type: 'authors', id: '1' } ],
           links: {
-            self: '/api/1.0/books/2/relationships/authors',
-            related: '/api/1.0/books/2/authors'
+            self: '/api/books/2/relationships/authors',
+            related: '/api/books/2/authors'
           }
         }
       },
-      links: { self: '/api/1.0/books/2' }
+      links: { self: '/api/books/2' }
     },
     {
       type: 'books',
@@ -460,12 +463,12 @@ Books with authors (non-simplified): {
         authors: {
           data: [ { type: 'authors', id: '3' } ],
           links: {
-            self: '/api/1.0/books/3/relationships/authors',
-            related: '/api/1.0/books/3/authors'
+            self: '/api/books/3/relationships/authors',
+            related: '/api/books/3/authors'
           }
         }
       },
-      links: { self: '/api/1.0/books/3' }
+      links: { self: '/api/books/3' }
     }
   ],
   included: [
@@ -478,7 +481,7 @@ Books with authors (non-simplified): {
         bio: 'British author of fiction, horror, and fantasy'
       },
       relationships: { books: { data: [] } },
-      links: { self: '/api/1.0/authors/1' }
+      links: { self: '/api/authors/1' }
     },
     {
       type: 'authors',
@@ -489,7 +492,7 @@ Books with authors (non-simplified): {
         bio: 'English humorist and fantasy author'
       },
       relationships: { books: { data: [] } },
-      links: { self: '/api/1.0/authors/2' }
+      links: { self: '/api/authors/2' }
     },
     {
       type: 'authors',
@@ -500,10 +503,10 @@ Books with authors (non-simplified): {
         bio: 'American author of horror and supernatural fiction'
       },
       relationships: { books: { data: [] } },
-      links: { self: '/api/1.0/authors/3' }
+      links: { self: '/api/authors/3' }
     }
   ],
-  links: { self: '/api/1.0/books?include=authors' }
+  links: { self: '/api/books?include=authors' }
 }
 
 ```
@@ -572,7 +575,7 @@ Books by Neil (simplified): {
       authors_ids: [ '1' ]
     }
   ],
-  links: { self: '/api/1.0/books?filters[authorName]=Neil' }
+  links: { self: '/api/books?filters[authorName]=Neil' }
 }
 Books by Neil (non-simplified): {
   data: [
@@ -592,7 +595,7 @@ Books by Neil (non-simplified): {
           ]
         }
       },
-      links: { self: '/api/1.0/books/1' }
+      links: { self: '/api/books/1' }
     },
     {
       type: 'books',
@@ -605,10 +608,10 @@ Books by Neil (non-simplified): {
       relationships: {
         authors: { data: [ { type: 'authors', id: '1' } ] }
       },
-      links: { self: '/api/1.0/books/2' }
+      links: { self: '/api/books/2' }
     }
   ],
-  links: { self: '/api/1.0/books?filters[authorName]=Neil' }
+  links: { self: '/api/books?filters[authorName]=Neil' }
 }
 Authors who wrote books with "Gods" (simplified): {
   data: [
@@ -620,7 +623,7 @@ Authors who wrote books with "Gods" (simplified): {
       books_ids: [ '1', '2' ]
     }
   ],
-  links: { self: '/api/1.0/authors?filters[bookTitle]=Gods' }
+  links: { self: '/api/authors?filters[bookTitle]=Gods' }
 }
 Authors who wrote books with "Gods" (non-simplified): {
   data: [
@@ -637,10 +640,10 @@ Authors who wrote books with "Gods" (non-simplified): {
           data: [ { type: 'books', id: '1' }, { type: 'books', id: '2' } ]
         }
       },
-      links: { self: '/api/1.0/authors/1' }
+      links: { self: '/api/authors/1' }
     }
   ],
-  links: { self: '/api/1.0/authors?filters[bookTitle]=Gods' }
+  links: { self: '/api/authors?filters[bookTitle]=Gods' }
 }
 Neil books with full author data: {
   data: [
@@ -684,7 +687,7 @@ Neil books with full author data: {
       ]
     }
   ],
-  links: { self: '/api/1.0/books?filters[authorName]=Neil&include=authors' }
+  links: { self: '/api/books?filters[authorName]=Neil&include=authors' }
 }
 ```
 

package/docs/GUIDE/GUIDE_2_7_Pagination_And_Ordering.md

@@ -15,7 +15,8 @@ await api.addResource('posts', {
   },
   relationships: {
     comments: { 
-      hasMany: 'comments', 
+      type: 'hasMany',
+      target: 'comments', 
       foreignKey: 'post_id',
       include: {
         limit: 5,  // Default limit for included comments
@@ -23,7 +24,7 @@ await api.addResource('posts', {
       }
     },
     tags: {
-      hasMany: 'tags',
+      type: 'manyToMany',
       through: 'post_tags',
       foreignKey: 'post_id',
       otherKey: 'tag_id',
@@ -69,7 +70,7 @@ await api.addResource('tags', {
   },
   relationships: {
     posts: {
-      hasMany: 'posts',
+      type: 'manyToMany',
       through: 'post_tags',
       foreignKey: 'tag_id',
       otherKey: 'post_id'
@@ -417,9 +418,9 @@ First page: {
     }
   },
   links: {
-    self: '/api/1.0/posts?sort=-created_at&&&page[size]=5',
-    first: '/api/1.0/posts?sort=-created_at&&&page[size]=5',
-    next: '/api/1.0/posts?sort=-created_at&&&page[size]=5&page[after]=created_at:1753675599811'
+    self: '/api/posts?sort=-created_at&&&page[size]=5',
+    first: '/api/posts?sort=-created_at&&&page[size]=5',
+    next: '/api/posts?sort=-created_at&&&page[size]=5&page[after]=created_at:1753675599811'
   }
 }
 
@@ -484,9 +485,9 @@ Second page: {
     }
   },
   links: {
-    self: '/api/1.0/posts?sort=-created_at&&&page[size]=5&page[after]=created_at:1753675599811',
-    first: '/api/1.0/posts?sort=-created_at&&&page[size]=5',
-    next: '/api/1.0/posts?sort=-created_at&&&page[size]=5&page[after]=created_at:1753675599797'
+    self: '/api/posts?sort=-created_at&&&page[size]=5&page[after]=created_at:1753675599811',
+    first: '/api/posts?sort=-created_at&&&page[size]=5',
+    next: '/api/posts?sort=-created_at&&&page[size]=5&page[after]=created_at:1753675599797'
   }
 }
 ```
@@ -587,9 +588,9 @@ First multiField page: {
     }
   },
   links: {
-    self: '/api/1.0/posts?sort=view_count&sort=-created_at&&&page[size]=5',
-    first: '/api/1.0/posts?sort=view_count&sort=-created_at&&&page[size]=5',
-    next: '/api/1.0/posts?sort=view_count&sort=-created_at&&&page[size]=5&page[after]=view_count:74,created_at:1753676192069'
+    self: '/api/posts?sort=view_count&sort=-created_at&&&page[size]=5',
+    first: '/api/posts?sort=view_count&sort=-created_at&&&page[size]=5',
+    next: '/api/posts?sort=view_count&sort=-created_at&&&page[size]=5&page[after]=view_count:74,created_at:1753676192069'
   }
 }
 Next multiField page: {
@@ -658,9 +659,9 @@ Next multiField page: {
     }
   },
   links: {
-    self: '/api/1.0/posts?sort=view_count&sort=-created_at&&&page[size]=5&page[after]=view_count:74,created_at:1753676192069',
-    first: '/api/1.0/posts?sort=view_count&sort=-created_at&&&page[size]=5',
-    next: '/api/1.0/posts?sort=view_count&sort=-created_at&&&page[size]=5&page[after]=view_count:290,created_at:1753676192056'
+    self: '/api/posts?sort=view_count&sort=-created_at&&&page[size]=5&page[after]=view_count:74,created_at:1753676192069',
+    first: '/api/posts?sort=view_count&sort=-created_at&&&page[size]=5',
+    next: '/api/posts?sort=view_count&sort=-created_at&&&page[size]=5&page[after]=view_count:290,created_at:1753676192056'
   }
 }
 ```
@@ -778,10 +779,10 @@ Popular sort: {
     pagination: { page: 1, pageSize: 5, pageCount: 5, total: 25, hasMore: true }
   },
   links: {
-    self: '/api/1.0/posts?sort=-view_count&&&page[number]=1&page[size]=5',
-    first: '/api/1.0/posts?sort=-view_count&&&page[number]=1&page[size]=5',
-    last: '/api/1.0/posts?sort=-view_count&&&page[number]=5&page[size]=5',
-    next: '/api/1.0/posts?sort=-view_count&&&page[number]=2&page[size]=5'
+    self: '/api/posts?sort=-view_count&&&page[number]=1&page[size]=5',
+    first: '/api/posts?sort=-view_count&&&page[number]=1&page[size]=5',
+    last: '/api/posts?sort=-view_count&&&page[number]=5&page[size]=5',
+    next: '/api/posts?sort=-view_count&&&page[number]=2&page[size]=5'
   }
 }
 Multisort: {
@@ -865,10 +866,10 @@ Multisort: {
     pagination: { page: 1, pageSize: 5, pageCount: 5, total: 25, hasMore: true }
   },
   links: {
-    self: '/api/1.0/posts?sort=published_at&sort=-view_count&&&page[number]=1&page[size]=5',
-    first: '/api/1.0/posts?sort=published_at&sort=-view_count&&&page[number]=1&page[size]=5',
-    last: '/api/1.0/posts?sort=published_at&sort=-view_count&&&page[number]=5&page[size]=5',
-    next: '/api/1.0/posts?sort=published_at&sort=-view_count&&&page[number]=2&page[size]=5'
+    self: '/api/posts?sort=published_at&sort=-view_count&&&page[number]=1&page[size]=5',
+    first: '/api/posts?sort=published_at&sort=-view_count&&&page[number]=1&page[size]=5',
+    last: '/api/posts?sort=published_at&sort=-view_count&&&page[number]=5&page[size]=5',
+    next: '/api/posts?sort=published_at&sort=-view_count&&&page[number]=2&page[size]=5'
   }
 }
 ```
@@ -881,7 +882,9 @@ When you include relationships in your query, they use the default `limit` and `
 // The relationship was defined with default limits:
 // relationships: {
 //   comments: { 
-//     hasMany: 'comments',
+//     type: 'hasMany',
+//     target: 'comments',
+//     foreignKey: 'post_id',
 //     include: {
 //       limit: 5,              // Always return max 5 comments
 //       orderBy: ['-created_at'] // Always order by newest first
@@ -966,10 +969,10 @@ Posts with comments: {
     pagination: { page: 1, pageSize: 3, pageCount: 9, total: 25, hasMore: true }
   },
   links: {
-    self: '/api/1.0/posts?include=comments&&sort=-created_at&page[number]=1&page[size]=3',
-    first: '/api/1.0/posts?include=comments&&sort=-created_at&page[number]=1&page[size]=3',
-    last: '/api/1.0/posts?include=comments&&sort=-created_at&page[number]=9&page[size]=3',
-    next: '/api/1.0/posts?include=comments&&sort=-created_at&page[number]=2&page[size]=3'
+    self: '/api/posts?include=comments&&sort=-created_at&page[number]=1&page[size]=3',
+    first: '/api/posts?include=comments&&sort=-created_at&page[number]=1&page[size]=3',
+    last: '/api/posts?include=comments&&sort=-created_at&page[number]=9&page[size]=3',
+    next: '/api/posts?include=comments&&sort=-created_at&page[number]=2&page[size]=3'
   }
 }
 
@@ -1012,10 +1015,10 @@ Posts with all relationships: {
     pagination: { page: 1, pageSize: 2, pageCount: 13, total: 25, hasMore: true }
   },
   links: {
-    self: '/api/1.0/posts?include=comments&include=tags&&sort=-created_at&page[number]=1&page[size]=2',
-    first: '/api/1.0/posts?include=comments&include=tags&&sort=-created_at&page[number]=1&page[size]=2',
-    last: '/api/1.0/posts?include=comments&include=tags&&sort=-created_at&page[number]=13&page[size]=2',
-    next: '/api/1.0/posts?include=comments&include=tags&&sort=-created_at&page[number]=2&page[size]=2'
+    self: '/api/posts?include=comments&include=tags&&sort=-created_at&page[number]=1&page[size]=2',
+    first: '/api/posts?include=comments&include=tags&&sort=-created_at&page[number]=1&page[size]=2',
+    last: '/api/posts?include=comments&include=tags&&sort=-created_at&page[number]=13&page[size]=2',
+    next: '/api/posts?include=comments&include=tags&&sort=-created_at&page[number]=2&page[size]=2'
   }
 }
 ```
@@ -1060,11 +1063,11 @@ console.log('Pagination meta:', JSON.stringify(pagedResult.meta, null, 2));
 
 ```text
 Pagination links: {
-  "self": "/api/1.0/posts?sort=-published_at&&&page[number]=2&page[size]=5",
-  "first": "/api/1.0/posts?sort=-published_at&&&page[number]=1&page[size]=5",
-  "last": "/api/1.0/posts?sort=-published_at&&&page[number]=5&page[size]=5",
-  "prev": "/api/1.0/posts?sort=-published_at&&&page[number]=1&page[size]=5",
-  "next": "/api/1.0/posts?sort=-published_at&&&page[number]=3&page[size]=5"
+  "self": "/api/posts?sort=-published_at&&&page[number]=2&page[size]=5",
+  "first": "/api/posts?sort=-published_at&&&page[number]=1&page[size]=5",
+  "last": "/api/posts?sort=-published_at&&&page[number]=5&page[size]=5",
+  "prev": "/api/posts?sort=-published_at&&&page[number]=1&page[size]=5",
+  "next": "/api/posts?sort=-published_at&&&page[number]=3&page[size]=5"
 }
 Pagination meta: {
   "pagination": {
@@ -1214,10 +1217,10 @@ Complex query results: {
     pagination: { page: 1, pageSize: 3, pageCount: 4, total: 12, hasMore: true }
   },
   links: {
-    self: '/api/1.0/posts?filters[title]=Even&sort=-view_count&sort=published_at&include=comments&include=tags&&page[number]=1&page[size]=3',
-    first: '/api/1.0/posts?filters[title]=Even&sort=-view_count&sort=published_at&include=comments&include=tags&&page[number]=1&page[size]=3',
-    last: '/api/1.0/posts?filters[title]=Even&sort=-view_count&sort=published_at&include=comments&include=tags&&page[number]=4&page[size]=3',
-    next: '/api/1.0/posts?filters[title]=Even&sort=-view_count&sort=published_at&include=comments&include=tags&&page[number]=2&page[size]=3'
+    self: '/api/posts?filters[title]=Even&sort=-view_count&sort=published_at&include=comments&include=tags&&page[number]=1&page[size]=3',
+    first: '/api/posts?filters[title]=Even&sort=-view_count&sort=published_at&include=comments&include=tags&&page[number]=1&page[size]=3',
+    last: '/api/posts?filters[title]=Even&sort=-view_count&sort=published_at&include=comments&include=tags&&page[number]=4&page[size]=3',
+    next: '/api/posts?filters[title]=Even&sort=-view_count&sort=published_at&include=comments&include=tags&&page[number]=2&page[size]=3'
   }
 }
 ```
@@ -1230,4 +1233,4 @@ The pagination and ordering system is designed to be efficient and predictable:
 
 ---
 
-[Previous: 2.6 Many to many (hasMany with through records)](./GUIDE_2_6_Many_To_Many.md) | [Back to Guide](./README.md)
+[Previous: 2.6 Many to Many Relationships](./GUIDE_2_6_Many_To_Many.md) | [Back to Guide](./README.md)

package/docs/GUIDE/GUIDE_2_8_Effects_of_PUT_and_PATCH.md

@@ -14,7 +14,7 @@ await api.addResource('publishers', {
     country: { type: 'string', required: true, max: 100 }
   },
   relationships: {
-    books: { hasMany: 'books', foreignKey: 'publisher_id' }
+    books: { type: 'hasMany', target: 'books', foreignKey: 'publisher_id' }
   }
 });
 await api.resources.publishers.createKnexTable();
@@ -27,7 +27,7 @@ await api.addResource('authors', {
     birth_year: { type: 'number', required: true }
   },
   relationships: {
-    books: { hasMany: 'books', foreignKey: 'author_id' }
+    books: { type: 'hasMany', target: 'books', foreignKey: 'author_id' }
   }
 });
 await api.resources.authors.createKnexTable();
@@ -53,7 +53,7 @@ await api.addResource('books', {
   relationships: {
     // Many-to-many relationship with genres
     genres: { 
-      hasMany: 'genres',
+      type: 'manyToMany',
       through: 'book_genres',
       foreignKey: 'book_id',
       otherKey: 'genre_id'

package/docs/GUIDE/GUIDE_2_Data_And_Relations.md

@@ -35,7 +35,7 @@ This guide has been split into the following sections for easier navigation:
 - Forward and reverse polymorphic search
 - Complex polymorphic filtering
 
-## [2.6 Many to many (hasMany with through records)](./GUIDE_2_6_Many_To_Many.md)
+## [2.6 Many to Many Relationships](./GUIDE_2_6_Many_To_Many.md)
 - Understanding many-to-many relationships
 - Working with pivot tables directly
 - Including many-to-many records

package/docs/GUIDE/GUIDE_3_Field_Transformations.md

@@ -624,7 +624,7 @@ await api.addResource('products', {
     }
   },
   relationships: {
-    reviews: { hasMany: 'reviews', foreignKey: 'product_id' }
+    reviews: { type: 'hasMany', target: 'reviews', foreignKey: 'product_id' }
   }
 });
 await api.resources.products.createKnexTable();
@@ -937,7 +937,7 @@ const db = knex({
 });
 
 // Create API instance
-const api = new Api({ name: 'blog-api', version: '1.0.0' });
+const api = new Api({ name: 'blog-api' });
 
 // Install plugins
 await api.use(RestApiPlugin);
@@ -952,7 +952,7 @@ await api.addResource('authors', {
     bio: { type: 'string', nullable: true }
   },
   relationships: {
-    posts: { hasMany: 'posts', foreignKey: 'author_id' }
+    posts: { type: 'hasMany', target: 'posts', foreignKey: 'author_id' }
   },
   tableName: 'authors'
 });
@@ -1032,7 +1032,7 @@ await api.addResource('authors', {
     }
   },
   relationships: {
-    posts: { hasMany: 'posts', foreignKey: 'author_id' }
+    posts: { type: 'hasMany', target: 'posts', foreignKey: 'author_id' }
   },
   tableName: 'authors'
 });
@@ -1134,7 +1134,7 @@ await api.addResource('authors', {
     }
   },
   relationships: {
-    posts: { hasMany: 'posts', foreignKey: 'author_id' }
+    posts: { type: 'hasMany', target: 'posts', foreignKey: 'author_id' }
   },
   tableName: 'authors'
 });