json-rest-api 1.0.24 → 1.0.26

package/plugins/core/lib/querying/knex-json-api-transformers-querying.js

@@ -350,37 +350,42 @@ export const toJsonApiRecord = (scope, record, scopeName) => {
 export const buildJsonApiResponse = async (scope, records, included = [], isSingle = false, scopeName, context) => {
   const {
     vars: {
-      schemaInfo: { schemaInstance, schemaRelationships: relationships, idProperty }
+      schemaInfo
     }
   } = scope
 
-  const idField = idProperty || 'id'
+  const {
+    schemaInstance,
+    schemaRelationships: relationships
+  } = schemaInfo
 
   const schemaStructure = getSchemaStructure(schemaInstance)
 
   const processedRecords = records.map(record => {
     const { [RELATIONSHIPS_KEY]: _relationships, ...cleanRecord } = record
+    const logicalRecord = translateRecordFromStorage(cleanRecord, schemaInfo)
     const jsonApiRecord = toJsonApiRecord(scope, cleanRecord, scopeName)
+    const resourceId = jsonApiRecord.id
 
     if (_relationships) {
       jsonApiRecord.relationships = _relationships
     }
 
     for (const [fieldName, fieldDef] of Object.entries(schemaStructure)) {
-      if (fieldDef.belongsTo && fieldDef.as && fieldName in cleanRecord) {
+      if (fieldDef.belongsTo && fieldDef.as && fieldName in logicalRecord) {
         jsonApiRecord.relationships = jsonApiRecord.relationships || {}
         if (!jsonApiRecord.relationships[fieldDef.as]) {
-          if (cleanRecord[fieldName] !== null && cleanRecord[fieldName] !== undefined) {
+          if (logicalRecord[fieldName] !== null && logicalRecord[fieldName] !== undefined) {
             const relationshipObject = {
               data: {
                 type: fieldDef.belongsTo,
-                id: String(cleanRecord[fieldName])
+                id: String(logicalRecord[fieldName])
               }
             }
 
             relationshipObject.links = {
-              self: buildRelationshipUrl(context, scope, scopeName, record[idField], fieldDef.as, true),
-              related: buildRelationshipUrl(context, scope, scopeName, record[idField], fieldDef.as, false)
+              self: buildRelationshipUrl(context, scope, scopeName, resourceId, fieldDef.as, true),
+              related: buildRelationshipUrl(context, scope, scopeName, resourceId, fieldDef.as, false)
             }
 
             jsonApiRecord.relationships[fieldDef.as] = relationshipObject
@@ -390,8 +395,8 @@ export const buildJsonApiResponse = async (scope, records, included = [], isSing
             }
 
             relationshipObject.links = {
-              self: buildRelationshipUrl(context, scope, scopeName, record[idField], fieldDef.as, true),
-              related: buildRelationshipUrl(context, scope, scopeName, record[idField], fieldDef.as, false)
+              self: buildRelationshipUrl(context, scope, scopeName, resourceId, fieldDef.as, true),
+              related: buildRelationshipUrl(context, scope, scopeName, resourceId, fieldDef.as, false)
             }
 
             jsonApiRecord.relationships[fieldDef.as] = relationshipObject
@@ -402,8 +407,8 @@ export const buildJsonApiResponse = async (scope, records, included = [], isSing
 
     Object.entries(relationships || {}).forEach(([relName, relDef]) => {
       if (relDef.belongsToPolymorphic) {
-        const typeValue = cleanRecord[relDef.belongsToPolymorphic.typeField]
-        const idValue = cleanRecord[relDef.belongsToPolymorphic.idField]
+        const typeValue = logicalRecord[relDef.belongsToPolymorphic.typeField]
+        const idValue = logicalRecord[relDef.belongsToPolymorphic.idField]
 
         if (typeValue && idValue) {
           jsonApiRecord.relationships = jsonApiRecord.relationships || {}
@@ -415,8 +420,8 @@ export const buildJsonApiResponse = async (scope, records, included = [], isSing
           }
 
           relationshipObject.links = {
-            self: buildRelationshipUrl(context, scope, scopeName, record[idField], relName, true),
-            related: buildRelationshipUrl(context, scope, scopeName, record[idField], relName, false)
+            self: buildRelationshipUrl(context, scope, scopeName, resourceId, relName, true),
+            related: buildRelationshipUrl(context, scope, scopeName, resourceId, relName, false)
           }
 
           jsonApiRecord.relationships[relName] = relationshipObject
@@ -427,8 +432,8 @@ export const buildJsonApiResponse = async (scope, records, included = [], isSing
           }
 
           relationshipObject.links = {
-            self: buildRelationshipUrl(context, scope, scopeName, record[idField], relName, true),
-            related: buildRelationshipUrl(context, scope, scopeName, record[idField], relName, false)
+            self: buildRelationshipUrl(context, scope, scopeName, resourceId, relName, true),
+            related: buildRelationshipUrl(context, scope, scopeName, resourceId, relName, false)
           }
 
           jsonApiRecord.relationships[relName] = relationshipObject

package/plugins/core/lib/querying/knex-pagination-helpers.js

@@ -1,3 +1,11 @@
+import { getFieldValue } from '../storage/storage-mapping.js'
+import { serializeJsonApiQuery } from '../querying-writing/connectors-query-parser.js'
+
+const buildJsonApiLink = (baseUrl, queryParams, page) => {
+  const queryString = serializeJsonApiQuery(queryParams, { page })
+  return queryString ? `${baseUrl}?${queryString}` : baseUrl
+}
+
 /**
  * Calculates pagination metadata from query results
  *
@@ -127,7 +135,7 @@ export const calculatePaginationMeta = (total, page, pageSize) => {
  * Purpose:
  * - JSON:API spec requires pagination links for easy navigation
  * - Preserves all other query parameters (filters, sorts, includes)
- * - Handles complex nested parameters like filter[author][name]=John
+ * - Uses the shared JSON:API query serializer for transport-supported params
  * - Only includes prev/next when applicable
  *
  * Data flow:
@@ -143,52 +151,20 @@ export const generatePaginationLinks = (urlPrefix, scopeName, queryParams, pagin
   const { page, pageCount, pageSize } = paginationMeta
   const links = {}
 
-  const otherParams = Object.entries(queryParams)
-    .filter(([key]) => key !== 'page')
-    .flatMap(([key, value]) => {
-      if (Array.isArray(value)) {
-        return value.length === 0
-          ? []
-          : value.map((v) => `${key}=${encodeURIComponent(v)}`)
-      }
-      if (typeof value === 'object' && value !== null) {
-        const parts = []
-        const processObject = (obj, prefix) => {
-          Object.entries(obj).forEach(([k, v]) => {
-            const newKey = prefix ? `${prefix}[${k}]` : `${key}[${k}]`
-            if (typeof v === 'object' && v !== null && !Array.isArray(v)) {
-              processObject(v, newKey)
-            } else if (v !== undefined && v !== null && !(Array.isArray(v) && v.length === 0)) {
-              parts.push(`${newKey}=${encodeURIComponent(v)}`)
-            }
-          })
-        }
-        processObject(value, key)
-        return parts
-      }
-      if (value === undefined || value === null) {
-        return []
-      }
-      return [`${key}=${encodeURIComponent(value)}`]
-    })
-    .filter(Boolean)
-    .join('&')
-
   const baseUrl = `${urlPrefix}/${scopeName}`
-  const queryPrefix = otherParams ? `?${otherParams}&` : '?'
 
-  links.self = `${baseUrl}${queryPrefix}page[number]=${page}&page[size]=${pageSize}`
+  links.self = buildJsonApiLink(baseUrl, queryParams, { number: page, size: pageSize })
 
   if (pageCount !== undefined) {
-    links.first = `${baseUrl}${queryPrefix}page[number]=1&page[size]=${pageSize}`
-    links.last = `${baseUrl}${queryPrefix}page[number]=${pageCount}&page[size]=${pageSize}`
+    links.first = buildJsonApiLink(baseUrl, queryParams, { number: 1, size: pageSize })
+    links.last = buildJsonApiLink(baseUrl, queryParams, { number: pageCount, size: pageSize })
 
     if (page > 1) {
-      links.prev = `${baseUrl}${queryPrefix}page[number]=${page - 1}&page[size]=${pageSize}`
+      links.prev = buildJsonApiLink(baseUrl, queryParams, { number: page - 1, size: pageSize })
     }
 
     if (page < pageCount) {
-      links.next = `${baseUrl}${queryPrefix}page[number]=${page + 1}&page[size]=${pageSize}`
+      links.next = buildJsonApiLink(baseUrl, queryParams, { number: page + 1, size: pageSize })
     }
   }
 
@@ -257,11 +233,13 @@ export const generatePaginationLinks = (urlPrefix, scopeName, queryParams, pagin
  * 4. Cursor used in 'next' link for fetching subsequent pages
  * 5. Enables efficient "WHERE (field1, field2) > (val1, val2)" queries
  */
-export const createCursor = (record, sortFields = ['id']) => {
+export const createCursor = (record, sortFields = ['id'], { schemaInfo = null } = {}) => {
   const parts = []
   sortFields.forEach(field => {
-    if (record[field] !== undefined) {
-      const value = record[field]
+    const value = schemaInfo
+      ? getFieldValue(record, schemaInfo, field)
+      : record[field]
+    if (value !== undefined) {
       const stringValue = value instanceof Date ? value.toISOString() : String(value)
       parts.push(`${field}:${encodeURIComponent(stringValue)}`)
     }
@@ -427,60 +405,36 @@ export const parseCursor = (cursor) => {
  * 4. Added to response.links for navigation
  * 5. Client uses next link to fetch subsequent pages
  */
-export const generateCursorPaginationLinks = (urlPrefix, scopeName, queryParams, records, pageSize, hasMore, sortFields = ['id']) => {
+export const generateCursorPaginationLinks = (
+  urlPrefix,
+  scopeName,
+  queryParams,
+  records,
+  pageSize,
+  hasMore,
+  sortFields = ['id'],
+  { schemaInfo = null } = {}
+) => {
   // Allow empty urlPrefix to generate relative links
   if (!records.length) return null
 
   const links = {}
   const baseUrl = `${urlPrefix}/${scopeName}`
-
-  const otherParams = Object.entries(queryParams)
-    .filter(([key]) => key !== 'page')
-    .flatMap(([key, value]) => {
-      if (Array.isArray(value)) {
-        return value.length === 0
-          ? []
-          : value.map((v) => `${key}=${encodeURIComponent(v)}`)
-      }
-      if (typeof value === 'object' && value !== null) {
-        const parts = []
-        const processObject = (obj, prefix) => {
-          Object.entries(obj).forEach(([k, v]) => {
-            const newKey = prefix ? `${prefix}[${k}]` : `${key}[${k}]`
-            if (typeof v === 'object' && v !== null && !Array.isArray(v)) {
-              processObject(v, newKey)
-            } else if (v !== undefined && v !== null && !(Array.isArray(v) && v.length === 0)) {
-              parts.push(`${newKey}=${encodeURIComponent(v)}`)
-            }
-          })
-        }
-        processObject(value, key)
-        return parts
-      }
-      if (value === undefined || value === null) {
-        return []
-      }
-      return [`${key}=${encodeURIComponent(value)}`]
-    })
-    .filter(Boolean)
-    .join('&')
-
-  const queryPrefix = otherParams ? `?${otherParams}&` : '?'
+  const selfPage = { size: pageSize }
 
   if (queryParams.page?.after) {
-    links.self = `${baseUrl}${queryPrefix}page[size]=${pageSize}&page[after]=${queryParams.page.after}`
+    selfPage.after = queryParams.page.after
   } else if (queryParams.page?.before) {
-    links.self = `${baseUrl}${queryPrefix}page[size]=${pageSize}&page[before]=${queryParams.page.before}`
-  } else {
-    links.self = `${baseUrl}${queryPrefix}page[size]=${pageSize}`
+    selfPage.before = queryParams.page.before
   }
 
-  links.first = `${baseUrl}${queryPrefix}page[size]=${pageSize}`
+  links.self = buildJsonApiLink(baseUrl, queryParams, selfPage)
+  links.first = buildJsonApiLink(baseUrl, queryParams, { size: pageSize })
 
   if (hasMore && records.length > 0) {
     const lastRecord = records[records.length - 1]
-    const nextCursor = createCursor(lastRecord, sortFields)
-    links.next = `${baseUrl}${queryPrefix}page[size]=${pageSize}&page[after]=${nextCursor}`
+    const nextCursor = createCursor(lastRecord, sortFields, { schemaInfo })
+    links.next = buildJsonApiLink(baseUrl, queryParams, { size: pageSize, after: nextCursor })
   }
 
   return links
@@ -543,7 +497,7 @@ export const generateCursorPaginationLinks = (urlPrefix, scopeName, queryParams,
  * 3. Added to response.meta.pagination
  * 4. Clients can use cursor directly or use the next link
  */
-export const buildCursorMeta = (records, pageSize, hasMore, sortFields = ['id']) => {
+export const buildCursorMeta = (records, pageSize, hasMore, sortFields = ['id'], { schemaInfo = null } = {}) => {
   const meta = {
     pageSize,
     hasMore
@@ -552,7 +506,7 @@ export const buildCursorMeta = (records, pageSize, hasMore, sortFields = ['id'])
   if (hasMore && records.length > 0) {
     const lastRecord = records[records.length - 1]
     meta.cursor = {
-      next: createCursor(lastRecord, sortFields)
+      next: createCursor(lastRecord, sortFields, { schemaInfo })
     }
   }
 

package/plugins/core/lib/querying/knex-relationship-includes.js

@@ -76,7 +76,11 @@
 
 import { applyFieldSelectionToQuery, buildFieldSelection } from '../querying-writing/knex-field-helpers.js'
 import { toJsonApiRecord } from './knex-json-api-transformers-querying.js'
-import { buildWindowedIncludeQuery, applyStandardIncludeConfig, buildOrderByClause } from './knex-window-queries.js'
+import {
+  buildWindowedIncludeSubquery,
+  applyStandardIncludeConfig,
+  buildOrderByClause
+} from './knex-window-queries.js'
 import { unwrapQueryBuilderState } from './query-builder-utils.js'
 import { RELATIONSHIPS_KEY, RELATIONSHIP_METADATA_KEY, ROW_NUMBER_KEY, COMPUTED_DEPENDENCIES_KEY, DEFAULT_QUERY_LIMIT } from '../querying-writing/knex-constants.js'
 import { RestApiResourceError } from '../../../../lib/rest-api-errors.js'
@@ -149,7 +153,8 @@ const applyScopeFiltersToIncludeQuery = async ({
   scopeName,
   requestContext,
   db,
-  tableName
+  tableName,
+  queryPurpose = 'include'
 }) => {
   const scopeObject = scopes[scopeName]
   if (!scopeObject?.applyQueryFilters) {
@@ -165,6 +170,7 @@ const applyScopeFiltersToIncludeQuery = async ({
     tableName: tableName || scopeObject.vars.schemaInfo.tableName,
     db,
     schemaInfo: scopeObject.vars.schemaInfo,
+    queryPurpose,
     storageAdapter
   }, buildScopedIncludeContext({
     requestContext,
@@ -981,46 +987,38 @@ export const loadHasMany = async (scope, deps) => {
 
       // Check if we should use window functions
       if (relDef.include?.strategy === 'window') {
-        try {
-        // Try to build window function query
-          if (fieldSelectionInfo?.queryFieldsToSelect?.length) {
-            throw new Error('Query projection fields require the standard include query path.')
-          }
+        let windowedQuery
 
-          const selectFields = fieldSelectionInfo?.fieldsToSelect || null
-
-          query = buildWindowedIncludeQuery(
+        if (fieldSelectionInfo?.queryFieldsToSelect?.length) {
+          log.debug('[INCLUDE] Query projection fields require the standard include query path')
+        } else {
+          windowedQuery = buildWindowedIncludeSubquery(
             knex,
             targetTable,
             foreignKey,
             mainIds,
-            selectFields,
+            fieldSelectionInfo?.fieldsToSelect || null,
             relDef.include || {},
             capabilities,
-            targetScopeObject.vars  // Pass target scope vars
+            targetScopeObject.vars
           )
+        }
+
+        if (windowedQuery) {
           const scopedQueryState = await applyScopeFiltersToIncludeQuery({
-            query,
+            query: windowedQuery.subquery,
             scopes,
             scopeName: targetScope,
             requestContext,
             db: knex,
             tableName: targetTable
           })
-          query = scopedQueryState.query
+          query = knex
+            .select('*')
+            .from(scopedQueryState.query.as('_windowed'))
+            .where(ROW_NUMBER_KEY, '<=', windowedQuery.effectiveLimit)
           usingWindowFunction = true
           log.debug('[INCLUDE] Using window function strategy with limits')
-        } catch (error) {
-        // If window functions not supported, this will throw a clear error
-          if (error.details?.requiredFeature === 'window_functions') {
-            throw error // Re-throw the descriptive error
-          }
-          // For other errors, fall back to standard query
-          log.warn('[INCLUDE] Window function query failed, falling back to standard query:', {
-            error: error.message,
-            stack: error.stack
-          })
-          usingWindowFunction = false
         }
       }
 
@@ -2114,7 +2112,8 @@ export const loadRelationshipIdentifiers = async (records, scopeName, scopes, kn
         scopeName: relDef.target,
         requestContext,
         db: knex,
-        tableName: targetTable
+        tableName: targetTable,
+        queryPurpose: 'relationship-identifiers'
       })
       query = scopedQueryState.query
 
@@ -2159,7 +2158,8 @@ export const loadRelationshipIdentifiers = async (records, scopeName, scopes, kn
         scopeName: targetScopeName,
         requestContext,
         db: knex,
-        tableName: targetTable
+        tableName: targetTable,
+        queryPurpose: 'relationship-identifiers'
       })
       query = scopedQueryState.query
 
@@ -2198,7 +2198,8 @@ export const loadRelationshipIdentifiers = async (records, scopeName, scopes, kn
           scopeName: targetScope,
           requestContext,
           db: knex,
-          tableName: targetTable
+          tableName: targetTable,
+          queryPurpose: 'relationship-identifiers'
         })
         query = scopedQueryState.query
 

package/plugins/core/lib/querying/knex-window-queries.js

@@ -2,82 +2,21 @@ import { RestApiResourceError } from '../../../../lib/rest-api-errors.js'
 import { ROW_NUMBER_KEY, DEFAULT_QUERY_LIMIT, DEFAULT_MAX_QUERY_LIMIT, DEFAULT_MAX_INCLUDE_LIMIT } from '../querying-writing/knex-constants.js'
 
 /**
- * Builds a window function query for limited includes per parent record
+ * Builds the inner window-function query used to limit included children per
+ * parent. Mandatory target filters must be applied to this inner query before
+ * the caller wraps it and filters by ROW_NUMBER.
  *
  * @param {Object} knex - Knex instance
  * @param {string} tableName - Target table name
  * @param {string} foreignKey - Foreign key field
  * @param {Array} parentIds - Parent record IDs
- * @param {Array} fieldsToSelect - Fields to select
- * @param {Object} includeConfig - Include configuration (limit, orderBy)
+ * @param {Array|string} fieldsToSelect - Fields to select, or '*'
+ * @param {Object} includeConfig - Include limit and ordering
  * @param {Object} capabilities - Database capabilities
- * @param {Object} scopeVars - Scope variables for defaults and limits
- * @returns {Object} Knex query
- *
- * @example
- * // Input: Load max 3 comments per article, ordered by newest first
- * const query = buildWindowedIncludeQuery(
- *   knex,
- *   'comments',
- *   'article_id',
- *   [1, 2, 3],  // Article IDs
- *   ['id', 'text', 'created_at'],
- *   { limit: 3, orderBy: ['-created_at'] },
- *   { windowFunctions: true },
- *   { queryDefaultLimit: 10 }
- * );
- *
- * // Generated SQL:
- * // WITH _windowed AS (
- * //   SELECT id, text, created_at, article_id,
- * //          ROW_NUMBER() OVER (
- * //            PARTITION BY article_id
- * //            ORDER BY created_at DESC
- * //          ) as __$jsonrestapi_rn$__
- * //   FROM comments
- * //   WHERE article_id IN (1, 2, 3)
- * // )
- * // SELECT * FROM _windowed
- * // WHERE __$jsonrestapi_rn$__ <= 3
- *
- * // Result: Each article gets max 3 comments, not 3 total
- *
- * @example
- * // Input: Database doesn't support window functions
- * const query = buildWindowedIncludeQuery(
- *   knex,
- *   'comments',
- *   'article_id',
- *   [1, 2, 3],
- *   '*',
- *   { limit: 5 },
- *   { windowFunctions: false, dbInfo: { client: 'mysql', version: '5.7' } }
- * );
- *
- * // Throws RestApiResourceError:
- * // "Include limits require window function support. Your database (mysql 5.7)
- * //  does not support this feature. Window functions are supported in:
- * //  PostgreSQL 8.4+, MySQL 8.0+, MariaDB 10.2+, SQLite 3.25+, SQL Server 2005+"
- *
- * @description
- * Used by:
- * - loadHasMany when strategy: 'window' and database supports window functions
- * - Enables per-parent limits for one-to-many relationships
- *
- * Purpose:
- * - Solves the "N+1 limit" problem where you want X records per parent
- * - Without window functions, LIMIT 10 gives 10 total across all parents
- * - With window functions, each parent gets up to 10 related records
- * - Critical for consistent API responses with includes
- *
- * Data flow:
- * 1. Creates subquery with ROW_NUMBER() partitioned by foreign key
- * 2. Numbers rows within each partition based on orderBy
- * 3. Outer query filters to keep only rows within limit
- * 4. Returns query ready for execution
- * 5. Caller removes the ROW_NUMBER column from results
+ * @param {Object} scopeVars - Resource query limits
+ * @returns {{ subquery: Object, effectiveLimit: number }} Inner query and validated limit
  */
-export const buildWindowedIncludeQuery = (
+export const buildWindowedIncludeSubquery = (
   knex,
   tableName,
   foreignKey,
@@ -137,13 +76,7 @@ export const buildWindowedIncludeQuery = (
     subquery.select(fieldsWithFK)
   }
 
-  // Wrap in outer query to filter by row number
-  const query = knex
-    .select('*')
-    .from(subquery.as('_windowed'))
-    .where(ROW_NUMBER_KEY, '<=', effectiveLimit)
-
-  return query
+  return { subquery, effectiveLimit }
 }
 
 /**
@@ -175,7 +108,7 @@ export const buildWindowedIncludeQuery = (
  *
  * @description
  * Used by:
- * - buildWindowedIncludeQuery for PARTITION BY ordering
+ * - buildWindowedIncludeSubquery for PARTITION BY ordering
  * - applyStandardIncludeConfig for regular ORDER BY
  * - Query builders that need consistent sort syntax
  *

package/plugins/core/lib/querying/storage-adapter-utils.js

@@ -1,5 +1,9 @@
 export const createStorageAdapterUtilities = (hookParams, { getStorageAdapter } = {}) => {
   const context = hookParams?.context || {}
+  const activeQuery = context.knexQuery || {}
+  const activeScopeName = activeQuery.scopeName
+  const activeTableName = activeQuery.tableName
+  const activeStorageAdapter = activeQuery.storageAdapter || context.storageAdapter
   const storageCache = new Map()
 
   const fetchStorageAdapter = (scopeName) => {
@@ -7,13 +11,9 @@ export const createStorageAdapterUtilities = (hookParams, { getStorageAdapter }
     if (storageCache.has(scopeName)) return storageCache.get(scopeName)
 
     let adapter = null
-    if (scopeName === context?.knexQuery?.scopeName) {
-      adapter = context.storageAdapter ||
-        context.knexQuery?.storageAdapter ||
+    if (scopeName === activeScopeName) {
+      adapter = activeStorageAdapter ||
         (typeof getStorageAdapter === 'function' ? getStorageAdapter(scopeName) : null)
-      if (adapter && !context.storageAdapter) {
-        context.storageAdapter = adapter
-      }
     } else {
       adapter = typeof getStorageAdapter === 'function' ? getStorageAdapter(scopeName) : null
     }
@@ -23,8 +23,8 @@ export const createStorageAdapterUtilities = (hookParams, { getStorageAdapter }
   }
 
   const defaultAliasForScope = (scopeName) => {
-    if (scopeName === context?.knexQuery?.scopeName) {
-      return context.knexQuery?.tableName || scopeName
+    if (scopeName === activeScopeName) {
+      return activeTableName || scopeName
     }
     return scopeName
   }

package/plugins/core/lib/querying/url-helpers.js

@@ -11,13 +11,12 @@
  * Priority order:
  * 1. context.urlPrefixOverride - Explicit override (from hooks or middleware)
  * 2. context.urlPrefix - Pre-calculated URL prefix
- * 3. Calculate from request if provided
- * 4. scope.vars.transport?.mountPath - Fallback to mount path
+ * 3. scope.vars.transport?.publicBaseUrl - Explicit public URL prefix
+ * 4. scope.vars.transport?.mountPath - Fallback to relative mount path
  * 5. '' - Empty string as final fallback
  *
  * @param {Object} context - Request context (may have urlPrefixOverride or urlPrefix)
  * @param {Object} scope - Scope/resource object with transport vars
- * @param {Object} req - Optional Express request object for auto-calculation
  * @returns {string} The final URL prefix to use
  *
  * @example
@@ -25,10 +24,10 @@
  * const urlPrefix = getUrlPrefix(context, scope);
  *
  * @example
- * // With request object for auto-calculation
- * const urlPrefix = getUrlPrefix({}, api, req);
+ * // With explicit public base URL
+ * const urlPrefix = getUrlPrefix({}, { vars: { transport: { publicBaseUrl: 'https://api.example.com/api' } } });
  */
-export function getUrlPrefix (context, scope, req = null) {
+export function getUrlPrefix (context, scope) {
   // Priority 1: Explicit override
   if (context?.urlPrefixOverride) {
     return context.urlPrefixOverride
@@ -39,21 +38,10 @@ export function getUrlPrefix (context, scope, req = null) {
     return context.urlPrefix
   }
 
-  // Priority 3: Calculate from request if provided
-  if (req) {
-    const protocol = req.get?.('x-forwarded-proto') ||
-      req.headers?.['x-forwarded-proto'] ||
-      req.protocol ||
-      'http'
-    const host = req.get?.('x-forwarded-host') ||
-      req.headers?.['x-forwarded-host'] ||
-      req.get?.('host') ||
-      req.headers?.host
-    const mountPath = scope?.vars?.transport?.mountPath || ''
-
-    if (host) {
-      return `${protocol}://${host}${mountPath}`
-    }
+  // Priority 3: Explicit public URL prefix configured by the transport
+  const publicBaseUrl = scope?.vars?.transport?.publicBaseUrl
+  if (publicBaseUrl) {
+    return String(publicBaseUrl).replace(/\/+$/, '')
   }
 
   // Priority 4: Fallback to mount path

package/plugins/core/lib/querying-writing/connectors-query-parser.js

@@ -163,3 +163,54 @@ export function parseJsonApiQuery (queryString) {
 
   return result
 }
+
+const hasSerializableValue = (value) => (
+  value !== undefined &&
+  value !== null &&
+  !(Array.isArray(value) && value.length === 0)
+)
+
+const stringifyQueryValue = (value) => {
+  if (value instanceof Date) return value.toISOString()
+  if (Array.isArray(value)) return value.map(stringifyQueryValue).join(',')
+  return String(value)
+}
+
+const appendCommaList = (params, key, value) => {
+  if (!hasSerializableValue(value)) return
+  const serialized = Array.isArray(value)
+    ? value.map(stringifyQueryValue).filter((entry) => entry.length > 0).join(',')
+    : stringifyQueryValue(value)
+
+  if (serialized) {
+    params.set(key, serialized)
+  }
+}
+
+const appendScopedParams = (params, publicName, values) => {
+  if (!values || typeof values !== 'object' || Array.isArray(values)) return
+
+  for (const [key, value] of Object.entries(values)) {
+    if (!key || !hasSerializableValue(value)) continue
+    params.set(`${publicName}[${key}]`, stringifyQueryValue(value))
+  }
+}
+
+/**
+ * Serializes internal REST API query parameters to public JSON:API query string form.
+ *
+ * This is intentionally the inverse of parseJsonApiQuery for the supported transport
+ * contract: include, sort, filter[...], fields[...], and page[...].
+ */
+export function serializeJsonApiQuery (queryParams = {}, { page } = {}) {
+  const params = new URLSearchParams()
+  const effectivePage = page === undefined ? queryParams.page : page
+
+  appendCommaList(params, 'include', queryParams.include)
+  appendCommaList(params, 'sort', queryParams.sort)
+  appendScopedParams(params, 'filter', queryParams.filters || queryParams.filter)
+  appendScopedParams(params, 'fields', queryParams.fields)
+  appendScopedParams(params, 'page', effectivePage)
+
+  return params.toString()
+}