json-rest-api 1.0.22 → 1.0.24

package/plugins/core/rest-api-plugin-methods/get.js

@@ -1,8 +1,9 @@
 import { RestApiResourceError } from '../../../lib/rest-api-errors.js'
-import { validateGetPayload } from '../lib/querying-writing/payload-validators.js'
 import { normalizeRecordAttributes } from '../lib/querying-writing/database-value-normalizers.js'
 import { getRequestedComputedFields } from '../lib/querying-writing/knex-field-helpers.js'
 import { transformJsonApiToSimplified } from '../lib/querying-writing/simplified-helpers.js'
+import { getRequestContracts, validateRequestContractOrThrow } from '../lib/querying-writing/request-contracts.js'
+import { requireExistingResourceId } from '../lib/querying-writing/resource-id-normalization.js'
 import { cascadeConfig } from './common.js'
 
 /**
@@ -41,11 +42,11 @@ export default async function getMethod ({
 
   // Assign common context properties
   context.schemaInfo = scopes[scopeName].vars.schemaInfo
-  context.queryParams = params.queryParams || {}
-
-  // These only make sense as parameter per query
-  context.queryParams.fields = cascadeConfig('fields', [context.queryParams], {})
-  context.queryParams.include = cascadeConfig('include', [context.queryParams], [])
+  const rawQueryParams = params.queryParams || {}
+  context.queryParams = {
+    fields: cascadeConfig('fields', [rawQueryParams], {}),
+    include: cascadeConfig('include', [rawQueryParams], [])
+  }
 
   context.transaction = params.transaction
   context.db = context.transaction || api.knex.instance
@@ -56,14 +57,28 @@ export default async function getMethod ({
   const schemaStructure = context.schemaInfo.schemaInstance.structure
   const schemaRelationships = context.schemaInfo.schemaRelationships
 
-  context.id = params.id
-
-  // Validate GET request to ensure required parameters are present and properly formatted.
-  // This checks that 'id' parameter exists and is not empty (you can't GET without an ID),
-  // validates 'include' contains valid relationship names (not arbitrary fields), and ensures
-  // 'fields' for sparse fieldsets follow the format fields[type]=comma,separated,list.
-  // Example: validates id: '123' exists, include: ['author', 'tags'] are real relationships.
-  validateGetPayload({ id: context.id, queryParams: context.queryParams }, vars.includeDepthLimit)
+  const requestContracts = getRequestContracts({
+    scopeName,
+    schemaInfo: context.schemaInfo,
+    includeDepthLimit: vars.includeDepthLimit,
+    sortableFields: vars.sortableFields
+  })
+  const normalizedId = requireExistingResourceId(params.id, {
+    scopeOptions,
+    vars,
+    scopeName
+  })
+  const validatedRequest = validateRequestContractOrThrow(
+    requestContracts.get,
+    {
+      id: normalizedId,
+      queryParams: context.queryParams
+    },
+    'GET request parameters are invalid'
+  )
+
+  context.id = validatedRequest.id
+  context.queryParams = validatedRequest.queryParams || {}
 
   // Fetch minimal record for authorization checks
   const minimalRecord = await helpers.dataGetMinimal({

package/plugins/core/rest-api-plugin-methods/patch-relationship.js

@@ -1,3 +1,6 @@
+import { handleWriteMethodError } from './common.js'
+import { requireExistingResourceId } from '../lib/querying-writing/resource-id-normalization.js'
+
 /**
  * PATCH RELATIONSHIP
  * Completely replaces a relationship
@@ -8,9 +11,13 @@
  * @param {object|array} relationshipData - New relationship data
  * @returns {Promise<void>} 204 No Content
  */
-export default async function patchRelationshipMethod ({ params, context, vars, helpers, scope, scopes, runHooks, scopeName, api }) {
+export default async function patchRelationshipMethod ({ params, context, vars, helpers, scope, scopes, runHooks, scopeOptions, scopeName, api, log }) {
   context.method = 'patchRelationship'
-  context.id = params.id
+  context.id = requireExistingResourceId(params.id, {
+    scopeOptions,
+    vars,
+    scopeName
+  })
   context.relationshipName = params.relationshipName
 
   // Transaction handling
@@ -50,6 +57,6 @@ export default async function patchRelationshipMethod ({ params, context, vars,
 
     // 204 No Content
   } catch (error) {
-    await handleWriteMethodError(error, context, 'PATCH_RELATIONSHIP', scopeName, log)
+    await handleWriteMethodError(error, context, 'PATCH_RELATIONSHIP', scopeName, log, runHooks)
   }
 }

package/plugins/core/rest-api-plugin-methods/patch.js

@@ -1,8 +1,12 @@
-import { RestApiResourceError } from '../../../lib/rest-api-errors.js'
-import { validatePatchPayload } from '../lib/querying-writing/payload-validators.js'
+import { RestApiResourceError, RestApiValidationError } from '../../../lib/rest-api-errors.js'
 import { processRelationships } from '../lib/writing/relationship-processor.js'
 import { updateManyToManyRelationship } from '../lib/writing/many-to-many-manipulations.js'
 import { ERROR_SUBTYPES } from '../lib/querying-writing/knex-constants.js'
+import { getRequestContracts, validateRequestContractOrThrow } from '../lib/querying-writing/request-contracts.js'
+import {
+  requireDocumentResourceId,
+  requireExistingResourceId
+} from '../lib/querying-writing/resource-id-normalization.js'
 import {
   setupCommonRequest,
   validateResourceAttributesBeforeWrite,
@@ -49,23 +53,63 @@ export default async function patchMethod ({
       api,
       helpers
     })
-    context.id = context.inputRecord.data.id
-
     // Run early hooks for pre-processing (e.g., file handling)
     await runHooks('beforeProcessing')
     await runHooks('beforeProcessingPatch')
 
-    // Validate PATCH payload to ensure the partial update actually contains changes.
-    // PATCH requests must include either attributes to update or relationships to modify -
-    // an empty PATCH is invalid. This prevents accidental no-op requests and ensures clients
-    // are explicit about what they want to change. Unlike PUT, PATCH preserves all fields
-    // not mentioned in the request.
-    // Example: data must have either attributes: {title: 'New'} or relationships: {author: {...}}
-    validatePatchPayload(context.inputRecord, scopes)
+    const requestContracts = getRequestContracts({
+      scopeName,
+      schemaInfo: context.schemaInfo,
+      includeDepthLimit: vars.includeDepthLimit,
+      sortableFields: vars.sortableFields
+    })
+    const normalizedPathId = params.id === undefined
+      ? null
+      : requireExistingResourceId(params.id, {
+        scopeOptions,
+        vars,
+        scopeName
+      })
+
+    if (normalizedPathId && !context.inputRecord?.data?.id) {
+      context.inputRecord = {
+        ...context.inputRecord,
+        data: {
+          ...(context.inputRecord?.data || {}),
+          id: normalizedPathId
+        }
+      }
+    }
+
+    context.inputRecord = validateRequestContractOrThrow(
+      requestContracts.patch,
+      context.inputRecord,
+      'PATCH request body is invalid'
+    )
+    const normalizedBodyId = requireDocumentResourceId(context.inputRecord.data.id, {
+      scopeOptions,
+      vars
+    })
+
+    if (normalizedPathId && normalizedPathId !== normalizedBodyId) {
+      throw new RestApiValidationError(
+        `ID mismatch. URL path ID '${normalizedPathId}' does not match request body ID '${normalizedBodyId}'`,
+        {
+          fields: ['data.id'],
+          violations: [{
+            field: 'data.id',
+            rule: 'id_consistency',
+            message: 'Request body ID must match URL path ID when both are provided'
+          }]
+        }
+      )
+    }
+    context.inputRecord.data.id = normalizedBodyId
+    context.id = normalizedPathId || normalizedBodyId
 
     // Validate that user has read access to all related resources
     // This ensures users can only create relationships to resources they can access
-    await validateRelationshipAccess(context, context.inputRecord, helpers, runHooks, api)
+    await validateRelationshipAccess(context, context.inputRecord, helpers, api)
 
     // Extract foreign keys from JSON:API relationships and prepare many-to-many operations
     // Example: relationships.author -> author_id: '123' for storage

package/plugins/core/rest-api-plugin-methods/post-relationship.js

@@ -1,6 +1,10 @@
 import { RestApiResourceError, RestApiValidationError, RestApiPayloadError } from '../../../lib/rest-api-errors.js'
 import { findRelationshipDefinition, handleWriteMethodError } from './common.js'
 import { createPivotRecords } from '../lib/writing/many-to-many-manipulations.js'
+import {
+  normalizeRelationshipIdentifiers,
+  requireExistingResourceId
+} from '../lib/querying-writing/resource-id-normalization.js'
 
 /**
    * POST RELATIONSHIP
@@ -12,9 +16,13 @@ import { createPivotRecords } from '../lib/writing/many-to-many-manipulations.js
    * @param {array} relationshipData - Array of resource identifiers to add
    * @returns {Promise<void>} 204 No Content
   */
-export default async function postRelationshipMethod ({ params, context, vars, helpers, scope, scopes, runHooks, scopeName, api, log }) {
+export default async function postRelationshipMethod ({ params, context, vars, helpers, scope, scopes, runHooks, scopeOptions, scopeName, api, log }) {
   context.method = 'postRelationship'
-  context.id = params.id
+  context.id = requireExistingResourceId(params.id, {
+    scopeOptions,
+    vars,
+    scopeName
+  })
   context.relationshipName = params.relationshipName
   context.schemaInfo = scopes[scopeName].vars.schemaInfo
 
@@ -45,6 +53,7 @@ export default async function postRelationshipMethod ({ params, context, vars, h
     if (!Array.isArray(params.relationshipData)) {
       throw new RestApiPayloadError('POST to relationship requires array of resource identifiers')
     }
+    params.relationshipData = normalizeRelationshipIdentifiers(params.relationshipData, { api })
 
     // Check permissions
     await runHooks('checkPermissions')

package/plugins/core/rest-api-plugin-methods/post.js

@@ -1,6 +1,7 @@
-import { validatePostPayload } from '../lib/querying-writing/payload-validators.js'
 import { processRelationships } from '../lib/writing/relationship-processor.js'
+import { getRequestContracts, validateRequestContractOrThrow } from '../lib/querying-writing/request-contracts.js'
 import { createPivotRecords } from '../lib/writing/many-to-many-manipulations.js'
+import { requireDocumentResourceId } from '../lib/querying-writing/resource-id-normalization.js'
 import {
   setupCommonRequest,
   validateResourceAttributesBeforeWrite,
@@ -50,16 +51,28 @@ export default async function postMethod ({
     await runHooks('beforeProcessing')
     await runHooks('beforeProcessingPost')
 
-    // Validate POST payload to ensure it follows JSON:API format and references valid resources.
-    // This checks the payload has required 'data' object with 'type' and 'attributes', validates
-    // that data.type matches a real resource type (preventing creation of non-existent resources),
-    // and ensures any relationships reference valid resource types with proper ID format.
-    // Example: data.type: 'articles' must be a registered scope, relationships.author must reference 'users'.
-    validatePostPayload(context.inputRecord, scopes)
+    const requestContracts = getRequestContracts({
+      scopeName,
+      schemaInfo: context.schemaInfo,
+      includeDepthLimit: vars.includeDepthLimit,
+      sortableFields: vars.sortableFields
+    })
+    context.inputRecord = validateRequestContractOrThrow(
+      requestContracts.post,
+      context.inputRecord,
+      'POST request body is invalid'
+    )
+
+    if (context.inputRecord?.data?.id !== undefined) {
+      context.inputRecord.data.id = requireDocumentResourceId(context.inputRecord.data.id, {
+        scopeOptions,
+        vars
+      })
+    }
 
     // Validate that user has read access to all related resources
     // This ensures users can only create relationships to resources they can access
-    await validateRelationshipAccess(context, context.inputRecord, helpers, runHooks, api)
+    await validateRelationshipAccess(context, context.inputRecord, helpers, api)
 
     // Extract foreign keys from JSON:API relationships and prepare many-to-many operations
     // Example: relationships.author -> author_id: '123' for storage

package/plugins/core/rest-api-plugin-methods/put.js

@@ -1,10 +1,15 @@
-import { RestApiResourceError } from '../../../lib/rest-api-errors.js'
-import { validatePutPayload } from '../lib/querying-writing/payload-validators.js'
+import { RestApiResourceError, RestApiValidationError } from '../../../lib/rest-api-errors.js'
 import { processRelationships } from '../lib/writing/relationship-processor.js'
 import { updateManyToManyRelationship, createPivotRecords } from '../lib/writing/many-to-many-manipulations.js'
 import { ERROR_SUBTYPES } from '../lib/querying-writing/knex-constants.js'
+import { getRequestContracts, validateRequestContractOrThrow } from '../lib/querying-writing/request-contracts.js'
+import {
+  requireDocumentResourceId,
+  requireExistingResourceId
+} from '../lib/querying-writing/resource-id-normalization.js'
 import {
   setupCommonRequest,
+  validateCompleteReplacePayload,
   validateResourceAttributesBeforeWrite,
   validateRelationshipAccess,
   applyFieldSetters,
@@ -17,7 +22,9 @@ import {
  * PUT
  * Updates an existing top-level resource by completely replacing it.
  * This method supports updating both attributes and relationships (1:1 and n:n).
- * PUT is a complete replacement - any relationships not provided will be removed/nulled.
+ * Existing persisted values cannot be silently dropped: if a stored attribute or belongsTo
+ * relationship already has a value, PUT must include it explicitly. Relationship collections
+ * still follow replacement semantics when a relationships object is provided.
  * This method does NOT support creating new related resources via an `included` array.
  */
 export default async function putMethod ({
@@ -48,23 +55,63 @@ export default async function putMethod ({
       api,
       helpers
     })
-    context.id = context.inputRecord.data.id
-
     // Run early hooks for pre-processing (e.g., file handling)
     await runHooks('beforeProcessing')
     await runHooks('beforeProcessingPut')
 
-    // Validate PUT payload to ensure it's a complete resource replacement operation.
-    // PUT requires the full resource representation including ID (unlike POST which generates ID).
-    // It validates that data.id matches the URL parameter, prevents 'included' array (which is
-    // read-only), and ensures the payload represents a complete replacement. Any fields not
-    // provided will be removed or reset to defaults - this is the key difference from PATCH.
-    // Example: PUT to /articles/123 must have data.id: '123' and all required fields.
-    validatePutPayload(context.inputRecord, scopes)
+    const requestContracts = getRequestContracts({
+      scopeName,
+      schemaInfo: context.schemaInfo,
+      includeDepthLimit: vars.includeDepthLimit,
+      sortableFields: vars.sortableFields
+    })
+    const normalizedPathId = params.id === undefined
+      ? null
+      : requireExistingResourceId(params.id, {
+        scopeOptions,
+        vars,
+        scopeName
+      })
+
+    if (normalizedPathId && !context.inputRecord?.data?.id) {
+      context.inputRecord = {
+        ...context.inputRecord,
+        data: {
+          ...(context.inputRecord?.data || {}),
+          id: normalizedPathId
+        }
+      }
+    }
+
+    context.inputRecord = validateRequestContractOrThrow(
+      requestContracts.put,
+      context.inputRecord,
+      'PUT request body is invalid'
+    )
+    const normalizedBodyId = requireDocumentResourceId(context.inputRecord.data.id, {
+      scopeOptions,
+      vars
+    })
+
+    if (normalizedPathId && normalizedPathId !== normalizedBodyId) {
+      throw new RestApiValidationError(
+        `ID mismatch. URL path ID '${normalizedPathId}' does not match request body ID '${normalizedBodyId}'`,
+        {
+          fields: ['data.id'],
+          violations: [{
+            field: 'data.id',
+            rule: 'id_consistency',
+            message: 'Request body ID must match URL path ID when both are provided'
+          }]
+        }
+      )
+    }
+    context.inputRecord.data.id = normalizedBodyId
+    context.id = normalizedPathId || normalizedBodyId
 
     // Validate that user has read access to all related resources
     // This ensures users can only create relationships to resources they can access
-    await validateRelationshipAccess(context, context.inputRecord, helpers, runHooks, api)
+    await validateRelationshipAccess(context, context.inputRecord, helpers, api)
 
     // Extract foreign keys from JSON:API relationships and prepare many-to-many operations
     // Example: relationships.author -> author_id: '123' for storage
@@ -74,13 +121,6 @@ export default async function putMethod ({
       { context }
     )
 
-    await validateResourceAttributesBeforeWrite({
-      context,
-      schema,
-      belongsToUpdates,
-      runHooks
-    })
-
     // Check existence first
     context.exists = await helpers.dataExists({
       scopeName,
@@ -108,8 +148,20 @@ export default async function putMethod ({
       context.minimalRecord = minimalRecord
     }
 
+    validateCompleteReplacePayload({
+      context,
+      belongsToUpdates
+    })
+
+    await validateResourceAttributesBeforeWrite({
+      context,
+      schema,
+      belongsToUpdates,
+      runHooks
+    })
+
     // For PUT, we also need to handle relationships that are NOT provided
-    // (they should be set to null/empty as PUT is a complete replacement)
+    // (they should be set to null/empty when a relationships object is provided)
     const allRelationships = {}
 
     // Collect all defined relationships for this resource

package/plugins/core/rest-api-plugin-methods/query.js

@@ -1,8 +1,8 @@
-import { RestApiValidationError } from '../../../lib/rest-api-errors.js'
-import { validateQueryPayload } from '../lib/querying-writing/payload-validators.js'
 import { normalizeRecordAttributes } from '../lib/querying-writing/database-value-normalizers.js'
 import { getRequestedComputedFields } from '../lib/querying-writing/knex-field-helpers.js'
+import { getEffectiveSortableFields } from '../lib/querying/query-field-sort-helpers.js'
 import { transformJsonApiToSimplified } from '../lib/querying-writing/simplified-helpers.js'
+import { getRequestContracts, validateRequestContractOrThrow } from '../lib/querying-writing/request-contracts.js'
 import { cascadeConfig } from './common.js'
 
 /**
@@ -61,66 +61,28 @@ export default async function queryMethod ({
   context.scopeName = scopeName
 
   // These are just shortcuts used in this function and will be returned
-  const searchSchema = context.schemaInfo.searchSchemaInstance
   const schemaStructure = context.schemaInfo.schemaInstance.structure
   const schemaRelationships = context.schemaInfo.schemaRelationships
 
   // Sortable fields and sort (mab)
-  context.sortableFields = vars.sortableFields
+  context.sortableFields = getEffectiveSortableFields(vars)
   // Apply default sort if no sort specified
   if (context.queryParams.sort.length === 0 && vars.defaultSort) {
     context.queryParams.sort = Array.isArray(vars.defaultSort) ? vars.defaultSort : [vars.defaultSort]
   }
 
-  // Validate query parameters to ensure they follow JSON:API specification and security rules.
-  // This checks that filters are valid field names, sort fields exist in sortableFields array
-  // (preventing SQL injection), pagination uses valid page[size]/page[number] format, and include
-  // paths reference real relationships. Example: sort: ['-createdAt', 'title'] is checked against
-  // sortableFields to ensure users can't sort by sensitive fields like 'password_hash'.
-  validateQueryPayload({ queryParams: context.queryParams }, context.sortableFields, vars.includeDepthLimit)
-
-  // Validate search/filter parameters against searchSchema
-  if (context.queryParams.filters && Object.keys(context.queryParams.filters).length > 0) {
-    // Only allow filtering if searchSchema is defined
-    if (!searchSchema) {
-      throw new RestApiValidationError(
-        `Filtering is not enabled for resource '${scopeName}'. To enable filtering, add 'search: true' to schema fields or define a searchSchema.`,
-        {
-          fields: Object.keys(context.queryParams.filters).map(field => `filters.${field}`),
-          violations: [{
-            field: 'filters',
-            rule: 'filtering_not_enabled',
-            message: 'Resource does not have searchable fields defined'
-          }]
-        }
-      )
-    }
-
-    // Validate the filter parameters searchSchema
-    const { validatedObject, errors } = await searchSchema.validate(context.queryParams.filters, {
-      onlyObjectValues: true // Partial validation for filters
-    })
-
-    // If there are validation errors, throw an error
-    if (Object.keys(errors).length > 0) {
-      const violations = Object.entries(errors).map(([field, error]) => ({
-        field: `filters.${field}`,
-        rule: error.code || 'invalid_value',
-        message: error.message
-      }))
-
-      throw new RestApiValidationError(
-        'Invalid filter parameters',
-        {
-          fields: Object.keys(errors).map(field => `filters.${field}`),
-          violations
-        }
-      )
-    }
-
-    // Replace filter with validated/transformed values
-    context.queryParams.filters = validatedObject
-  }
+  const requestContracts = getRequestContracts({
+    scopeName,
+    schemaInfo: context.schemaInfo,
+    includeDepthLimit: vars.includeDepthLimit,
+    sortableFields: context.sortableFields
+  })
+  const validatedRequest = validateRequestContractOrThrow(
+    requestContracts.query,
+    { queryParams: context.queryParams },
+    'Query parameters are invalid'
+  )
+  context.queryParams = validatedRequest.queryParams || {}
 
   // Centralised checkPermissions function
   await scope.checkPermissions({

package/plugins/core/rest-api-plugin-methods/release.js

@@ -1,5 +1,3 @@
-import { ValidationError } from 'hooked-api'
-
 /**
  * release
  * Runs the hook that tells plugins to release resources

package/plugins/core/rest-api-plugin.js

@@ -16,6 +16,7 @@ import patchMethod from './rest-api-plugin-methods/patch.js'
 import deleteMethod from './rest-api-plugin-methods/delete.js'
 import enrichAttributesMethod from './rest-api-plugin-methods/enrich-attributes.js'
 import checkPermissionsMethod from './rest-api-plugin-methods/check-permissions.js'
+import applyQueryFiltersMethod from './rest-api-plugin-methods/apply-query-filters.js'
 import addRouteMethod from './rest-api-plugin-methods/add-route.js'
 import releaseMethod from './rest-api-plugin-methods/release.js'
 import { defaultDataHelpers } from './lib/querying-writing/default-data-helpers.js'
@@ -26,6 +27,7 @@ import postRelationshipMethod from './rest-api-plugin-methods/post-relationship.
 import getRelationshipMethod from './rest-api-plugin-methods/get-relationship.js'
 import patchRelationshipMethod from './rest-api-plugin-methods/patch-relationship.js'
 import deleteRelationshipMethod from './rest-api-plugin-methods/delete-relationship.js'
+import { defaultNormalizeResourceId } from './lib/querying-writing/resource-id-normalization.js'
 
 export const RestApiPlugin = {
   name: 'rest-api',
@@ -65,6 +67,9 @@ export const RestApiPlugin = {
       : true // Default true for better DX in programmatic API
 
     vars.idProperty = restApiOptions.idProperty || 'id'
+    vars.normalizeId = typeof restApiOptions.normalizeId === 'function'
+      ? restApiOptions.normalizeId
+      : defaultNormalizeResourceId
 
     // Return full record configuration for API and Transport
     // Support values: 'no', 'minimal', 'full'
@@ -148,6 +153,7 @@ export const RestApiPlugin = {
     // Non-URL methods
     addScopeMethod('enrichAttributes', enrichAttributesMethod)
     addScopeMethod('checkPermissions', checkPermissionsMethod)
+    addScopeMethod('applyQueryFilters', applyQueryFiltersMethod)
 
     // *********
     // Helpers

package/plugins/core/rest-api-positioning-plugin.js

@@ -1,8 +1,6 @@
 import {
   calculatePosition,
   getInitialPosition,
-  isValidPosition,
-  assignInitialPositions,
 } from './lib/fractional-positioning.js'
 import { createStorageAdapter } from './lib/storage/storage-adapter.js'
 
@@ -27,7 +25,7 @@ export const PositioningPlugin = {
     // Get configuration - hooked-api namespaces options by plugin name
     const positioningOptions = pluginOptions || {}
 
-    // Store configuration in vars (data only) - inspired by multihome pattern
+    // Store configuration in vars (data only) so hooks can use it without re-reading plugin options.
     vars.positioning = {
       field: positioningOptions.field || 'position',
       filters: positioningOptions.filters || [],
@@ -167,7 +165,7 @@ export const PositioningPlugin = {
           fieldExists = true
         } else {
           // Check if it's a relationship name (as property)
-          for (const [fieldName, fieldDef] of Object.entries(schema)) {
+          for (const [, fieldDef] of Object.entries(schema)) {
             if (fieldDef.as === filterField) {
               fieldExists = true
               break
@@ -419,7 +417,6 @@ export const PositioningPlugin = {
       log.debug('*** Position filter conditions', { scopeName, filterConditions })
 
       // Query existing items in the same position group
-      const knex = api.knex.instance
       const tableName = adapter.getTableName()
       const idProperty = schemaInfo.idProperty
       const idColumn = adapter.getIdColumn()