json-rest-api 1.0.7 → 1.0.8

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

@@ -0,0 +1,295 @@
+import { RestApiResourceError } from "../../../lib/rest-api-errors.js";
+import { findRelationshipDefinition } from "./common.js";
+
+/**
+ * GET RELATED
+ * Retrieves the actual related resources (full data)
+ * GET /api/articles/1/comments
+ * 
+ * @param {string} id - The ID of the parent resource
+ * @param {string} relationshipName - The name of the relationship
+ * @param {object} queryParams - Standard query parameters
+ * @returns {Promise<object>} Related resources with full data
+ */
+export default async function getRelatedMethod ({ params, context, vars, helpers, scope, scopes, runHooks, scopeName, api })  {
+  context.method = 'getRelated';
+  context.id = params.id;
+  context.relationshipName = params.relationshipName;
+  context.queryParams = params.queryParams || {};
+  context.schemaInfo = scopes[scopeName].vars.schemaInfo;
+  context.transaction = params.transaction;
+  context.db = context.transaction || api.knex.instance
+
+  // Validate the relationship exists
+  const relDef = findRelationshipDefinition(context.schemaInfo, context.relationshipName);
+
+  if (!relDef) {
+    throw new RestApiResourceError(
+      `Relationship '${context.relationshipName}' not found on resource '${scopeName}'`,
+      { subtype: 'relationship_not_found' }
+    );
+  }
+
+  // Determine target type - relationships are stored as strings
+  const targetType = relDef.belongsTo || relDef.hasMany || 
+                    relDef.manyToMany || relDef.hasOne;
+
+  if (!targetType || !scopes[targetType]) {
+    throw new RestApiResourceError(
+      `Related resource type '${targetType}' not found`,
+      { subtype: 'related_type_not_found' }
+    );
+  }
+
+  // Check permissions
+  await runHooks('checkPermissions');
+  await runHooks('checkPermissionsGetRelated');
+
+  // Verify parent exists
+  const exists = await helpers.dataExists({
+    scopeName,
+    context: { db: context.db, id: context.id, schemaInfo: context.schemaInfo }
+  });
+
+  if (!exists) {
+    throw new RestApiResourceError('Resource not found', { subtype: 'not_found' });
+  }
+
+  // Handle to-one relationships (belongsTo and hasOne)
+  // For example: GET /api/books/1/country or GET /api/books/1/publisher
+  if (relDef.belongsTo || relDef.hasOne) {
+    // OPTIMIZATION: Detect if we actually need to make two API calls
+    // 
+    // The naive approach always makes 2 calls:
+    // 1. Get parent with relationship included (fetches FULL related record)
+    // 2. Extract just the ID and fetch the same record again with queryParams
+    //
+    // This optimization checks if there are queryParams that would affect
+    // the related resource. If not, we can use the data from the first call.
+    const hasRelevantQueryParams = context.queryParams && (
+      // Check for includes on the related resource (e.g., ?include=some.nested.relation)
+      context.queryParams.include?.length > 0 ||
+      // Check for field selection on the related resource (e.g., ?fields[countries]=name,code)
+      context.queryParams.fields?.[targetType] ||
+      // Note: Filters and sorting don't make sense for a single to-one relationship
+      // so we don't check for them
+      false
+    );
+
+    if (hasRelevantQueryParams) {
+      // CASE 1: Has queryParams that affect the related resource
+      // We need to make two calls to properly apply the queryParams
+      
+      // First call: Get parent with minimal data (just need the related ID)
+      const parent = await scope.get({
+        id: context.id,
+        queryParams: { 
+          include: [context.relationshipName],
+          fields: { [scopeName]: vars.idProperty || 'id' } // Only fetch parent ID to minimize data
+        },
+        transaction: context.transaction,
+        simplified: false,
+        isTransport: params.isTransport
+      });
+
+      const relatedId = parent.data.relationships?.[context.relationshipName]?.data?.id;
+      if (!relatedId) {
+        return {
+          links: { self: `${vars.publicBaseUrl || vars.transport?.mountPath || ''}/${scopeName}/${context.id}/${context.relationshipName}` },
+          data: null
+        };
+      }
+
+      // Second call: Get the related resource with all queryParams applied
+      const related = await api.resources[targetType].get({
+        id: relatedId,
+        queryParams: context.queryParams,
+        transaction: context.transaction,
+        simplified: false,
+        isTransport: params.isTransport
+      });
+
+      return {
+        links: { self: `${vars.publicBaseUrl || vars.transport?.mountPath || ''}/${scopeName}/${context.id}/${context.relationshipName}` },
+        data: related.data,
+        included: related.included
+      };
+    } else {
+      // CASE 2: No queryParams that affect the related resource
+      // We can get everything in one call and extract from included
+      
+      // Single call: Get parent with full related resource included
+      const parent = await scope.get({
+        id: context.id,
+        queryParams: { 
+          include: [context.relationshipName],
+          fields: context.queryParams.fields // Respect any field selections for the parent
+        },
+        transaction: context.transaction,
+        simplified: false,
+        isTransport: params.isTransport
+      });
+
+      // Extract the related resource from the parent's relationships
+      const relatedId = parent.data.relationships?.[context.relationshipName]?.data?.id;
+      if (!relatedId) {
+        return {
+          links: { self: `${vars.publicBaseUrl || vars.transport?.mountPath || ''}/${scopeName}/${context.id}/${context.relationshipName}` },
+          data: null
+        };
+      }
+
+      // Find the full related resource in the included array
+      // The include system already fetched it for us!
+      const relatedResource = parent.included?.find(
+        r => r.type === targetType && r.id === relatedId
+      );
+
+      return {
+        links: { self: `${vars.publicBaseUrl || vars.transport?.mountPath || ''}/${scopeName}/${context.id}/${context.relationshipName}` },
+        data: relatedResource || null
+      };
+    }
+  }
+
+  // Handle simple hasMany (one-to-many)
+  if (relDef.hasMany && !relDef.through) {
+    // Check if this is a polymorphic relationship using 'via'
+    if (relDef.via) {
+      // Polymorphic hasMany relationship
+      // Example: publishers hasMany reviews via reviewable
+      const targetRelationships = scopes[targetType].vars.schemaInfo.schemaRelationships;
+      const viaRel = targetRelationships?.[relDef.via];
+      
+      if (!viaRel?.belongsToPolymorphic) {
+        throw new RestApiResourceError(
+          `Via relationship '${relDef.via}' not found or not polymorphic in '${targetType}'`,
+          { subtype: 'invalid_via_relationship' }
+        );
+      }
+      
+      const { typeField, idField } = viaRel.belongsToPolymorphic;
+      
+      // Add polymorphic filters
+      const filters = {
+        ...context.queryParams.filters,
+        [typeField]: scopeName,
+        [idField]: context.id
+      };
+      
+      const result = await api.resources[targetType].query({
+        queryParams: { ...context.queryParams, filters },
+        transaction: context.transaction,
+        simplified: false,
+        isTransport: params.isTransport
+      });
+      
+      if (!result.links) {
+        result.links = {};
+      }
+      result.links.self = `${vars.publicBaseUrl || vars.transport?.mountPath || ''}/${scopeName}/${context.id}/${context.relationshipName}`;
+      return result;
+    } else {
+      // Regular hasMany with foreignKey
+      const filters = {
+        ...context.queryParams.filters,
+        [relDef.foreignKey]: context.id
+      };
+
+      const result = await api.resources[targetType].query({
+        queryParams: { ...context.queryParams, filters },
+        transaction: context.transaction,
+        simplified: false,
+        isTransport: params.isTransport
+      });
+
+      if (!result.links) {
+        result.links = {};
+      }
+      result.links.self = `${vars.publicBaseUrl || vars.transport?.mountPath || ''}/${scopeName}/${context.id}/${context.relationshipName}`;
+      return result;
+    }
+  }
+
+  // Handle many-to-many relationships (hasMany with through)
+  // For example: GET /api/authors/1/books (where authors and books are linked via book_authors)
+  if (relDef.manyToMany || (relDef.hasMany && relDef.through)) {
+    // APPROACH: Query the pivot table directly
+    //
+    // Instead of:
+    // 1. Getting parent with relationship included to find related IDs
+    // 2. Trying to filter by id:[array] which doesn't work
+    //
+    // We query the pivot table (e.g., book_authors) filtered by the parent ID
+    // and include the target resources. This is simpler and uses existing
+    // API functionality without needing special array filter support.
+    
+    const pivotResource = relDef.through;
+    const foreignKey = relDef.foreignKey;
+    const otherKey = relDef.otherKey;
+    
+    // These should already be validated by scope-validations.js
+    if (!foreignKey || !otherKey) {
+      throw new Error(`Missing foreignKey or otherKey in many-to-many relationship`);
+    }
+    
+    // We need to find the relationship name on the pivot table that points to the target
+    // The pivot table should have a belongsTo relationship to the target resource
+    const pivotScope = scopes[pivotResource];
+    if (!pivotScope) {
+      throw new RestApiResourceError(
+        `Pivot table resource '${pivotResource}' not found`,
+        { subtype: 'pivot_table_not_found' }
+      );
+    }
+    
+    // Find the relationship name on the pivot table that points to the target
+    let targetRelationshipName = null;
+    const pivotSchema = pivotScope.vars.schemaInfo.schemaStructure;
+    for (const [fieldName, fieldDef] of Object.entries(pivotSchema)) {
+      if (fieldDef.belongsTo === targetType && fieldDef.as) {
+        targetRelationshipName = fieldDef.as;
+        break;
+      }
+    }
+    
+    if (!targetRelationshipName) {
+      throw new RestApiResourceError(
+        `Cannot find relationship to '${targetType}' in pivot table '${pivotResource}'`,
+        { subtype: 'pivot_relationship_not_found' }
+      );
+    }
+    
+    // Build filters for the pivot table
+    const pivotFilters = {
+      [foreignKey]: context.id
+    };
+    
+    // Query the pivot table with the target included
+    const pivotResult = await api.resources[pivotResource].query({
+      queryParams: {
+        filters: pivotFilters,
+        include: [targetRelationshipName],
+        // Pass through other query params that should apply to the included resources
+        fields: context.queryParams.fields,
+        sort: context.queryParams.sort,
+        page: context.queryParams.page
+      },
+      transaction: context.transaction,
+      simplified: false,
+      isTransport: params.isTransport
+    });
+    
+    // Extract the included target resources
+    const includedResources = pivotResult.included?.filter(r => r.type === targetType) || [];
+    
+    // Build the response
+    return {
+      links: {
+        self: `${vars.publicBaseUrl || vars.transport?.mountPath || ''}/${scopeName}/${context.id}/${context.relationshipName}`
+      },
+      data: includedResources,
+      meta: pivotResult.meta
+    };
+  }
+}

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

@@ -0,0 +1,62 @@
+
+import { RestApiResourceError } from "../../../lib/rest-api-errors.js";
+import { findRelationshipDefinition } from "./common.js";
+
+/**
+ * GET RELATIONSHIP
+ * Retrieves relationship linkage data (just resource identifiers)
+ * GET /api/articles/1/relationships/author
+ * 
+ * @param {string} id - The ID of the resource
+ * @param {string} relationshipName - The name of the relationship
+ * @returns {Promise<object>} Relationship linkage with links
+ */
+export default async function getRelationshipMethod ({ params, context, vars, helpers, scope, scopes, runHooks, scopeName, api }) {
+  context.method = 'getRelationship';
+  context.id = params.id;
+  context.relationshipName = params.relationshipName;
+  context.schemaInfo = scopes[scopeName].vars.schemaInfo;
+
+  // Validate the relationship exists
+  const relDef = findRelationshipDefinition(context.schemaInfo, context.relationshipName);
+
+  if (!relDef) {
+    throw new RestApiResourceError(
+      `Relationship '${context.relationshipName}' not found on resource '${scopeName}'`,
+      { subtype: 'relationship_not_found' }
+    );
+  }
+
+  // Check permissions
+  await runHooks('checkPermissions');
+  await runHooks('checkPermissionsGetRelationship');
+
+  // Reuse existing get method with minimal fields
+  const fullRecord = await scope.get({
+    id: context.id,
+    queryParams: {
+      include: [context.relationshipName],
+      fields: { [scopeName]: vars.idProperty || 'id' }
+    },
+    transaction: context.transaction,
+    simplified: false,
+    isTransport: params.isTransport
+  });
+
+  if (!fullRecord || !fullRecord.data) {
+    throw new RestApiResourceError('Resource not found', { subtype: 'not_found' });
+  }
+
+  // Extract just the relationship data
+  const relationshipData = fullRecord.data.relationships?.[context.relationshipName];
+
+  // Build response with links
+  return {
+    links: {
+      self: `${vars.publicBaseUrl || vars.transport?.mountPath || ''}/${scopeName}/${context.id}/relationships/${context.relationshipName}`,
+      related: `${vars.publicBaseUrl || vars.transport?.mountPath || ''}/${scopeName}/${context.id}/${context.relationshipName}`
+    },
+    data: relationshipData?.data || (relDef.hasMany || relDef.manyToMany ? [] : null)
+  };
+};
+

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

@@ -0,0 +1,187 @@
+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 { cascadeConfig } from './common.js';
+
+/**
+ * GET
+ * Retrieves a single resource by its type and ID.
+ * @param {(string|number)} id - The unique ID of the resource to fetch.
+ * @param {object} [queryParams={}] - Optional. An object to customize the query.
+ * @param {string} [queryParams.include] - A comma-separated string of relationship paths to sideload (e.g., "authors,publisher").
+ * @param {object} [queryParams.fields] - An object to request only specific fields (sparse fieldsets). Keys are resource types, values are comma-separated field names.
+ * @returns {Promise<object>} A Promise that resolves to the JSON:API response document.
+ */
+export default async function getMethod({ 
+  params, 
+  context, 
+  vars, 
+  helpers, 
+  scope, 
+  scopes, 
+  runHooks, 
+  apiOptions, 
+  pluginOptions, 
+  scopeOptions, 
+  scopeName,
+  api
+}) {
+  context.method = 'get';
+
+  // Determine which simplified setting to use based on transport
+  const isTransport = params.isTransport === true;
+  
+  // Use vars which automatically cascade from scope to global
+  const defaultSimplified = isTransport ? vars.simplifiedTransport : vars.simplifiedApi;
+  
+  // Get simplified setting - from params only (per-call override) or use default
+  context.simplified = params.simplified !== undefined ? params.simplified : defaultSimplified;
+
+  // 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], []);
+  
+  context.transaction = params.transaction;
+  context.db = context.transaction || api.knex.instance;
+
+  context.scopeName = scopeName;
+
+  // These are just shortcuts used in this function and will be returned
+  const schemaStructure = context.schemaInfo.schema.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);
+
+  // Fetch minimal record for authorization checks
+  const minimalRecord = await helpers.dataGetMinimal({
+    scopeName,
+    context,
+    runHooks
+  });
+
+  if (!minimalRecord) {
+    throw new RestApiResourceError(
+      `Resource not found`,
+      { 
+        subtype: 'not_found',
+        resourceType: scopeName,
+        resourceId: context.id
+      }
+    );
+  }
+
+  context.minimalRecord = minimalRecord;
+
+  // Centralised checkPermissions function
+  await scope.checkPermissions({
+    method: 'get',
+    auth: context.auth,
+    id: context.id,
+    minimalRecord: context.minimalRecord,
+    transaction: context.transaction
+  });
+  
+  await runHooks('beforeData');
+  await runHooks('beforeDataGet');
+
+  context.record = await helpers.dataGet({
+    scopeName,
+    context,
+    runHooks
+  });
+
+  // Check if record was found - storage layer returns null/undefined for non-existent records.
+  // This generates a proper 404 error with JSON:API error format instead of returning empty data.
+  if (!context.record || !context.record.data) {
+    throw new RestApiResourceError(
+      `Resource not found`,
+      { 
+        subtype: 'not_found',
+        resourceType: scopeName,
+        resourceId: context.id
+      }
+    );
+  }
+
+  // Normalize database values (e.g., convert 1/0 to true/false for booleans)
+  context.record = normalizeRecordAttributes(context.record, scopes);
+
+  await runHooks('checkDataPermissions');
+  await runHooks('checkDataPermissionsGet');
+  
+  // Make a backup
+  context.originalRecord = structuredClone(context.record);
+
+  // This will enhance record, which is the WHOLE JSON:API record
+  await runHooks('enrichRecord');
+  
+  // Get computed field information for main resource
+  const computedFields = scope.vars.schemaInfo?.computed || {};
+  const requestedFields = context.queryParams.fields?.[scopeName];
+  const requestedComputedFields = getRequestedComputedFields(scopeName, requestedFields, computedFields);
+  
+  // Enrich attributes for the main resource
+  // Pass computedDependencies from context (set by dataGet in Knex plugin)
+  // This tells enrichAttributes which fields to remove after computation
+  context.record.data.attributes = await scope.enrichAttributes({ 
+    attributes: context.record.data.attributes, 
+    parentContext: context,
+    requestedComputedFields: requestedComputedFields,
+    isMainResource: true,
+    computedDependencies: context.computedDependencies  // Fields to remove if not requested
+  });
+  
+  for (const entry of (context.record.included || [])) {
+    const entryScope = scopes[entry.type];
+    const entryComputed = entryScope.vars.schemaInfo?.computed || {};
+    const entryRequestedFields = context.queryParams.fields?.[entry.type];
+    const entryRequestedComputed = getRequestedComputedFields(
+      entry.type, 
+      entryRequestedFields, 
+      entryComputed
+    );
+    
+    entry.attributes = await entryScope.enrichAttributes({ 
+      attributes: entry.attributes, 
+      parentContext: context,
+      requestedComputedFields: entryRequestedComputed,
+      isMainResource: false,
+      computedDependencies: entry.__$jsonrestapi_computed_deps$__
+    });
+  }
+  
+  await runHooks('enrichRecordWithRelationships');
+
+  // The called hooks should NOT change context.record
+  await runHooks('finish');
+  await runHooks('finishGet');
+  
+  // Get schema info for transformation
+  context.schemaInfo = scopes[scopeName].vars.schemaInfo;
+  
+  // Transform output if in simplified mode
+  if (context.simplified) {
+    // Convert JSON:API response back to simplified format
+    // Example: {data: {type: 'posts', id: '1', attributes: {title: 'My Post'}, relationships: {author: {data: {type: 'users', id: '123'}}}}} 
+    // becomes: {id: '1', title: 'My Post', author_id: '123'} - flattens structure and restores foreign keys
+    return transformJsonApiToSimplified(
+      { record: context.record },
+      { context: { schemaStructure, schemaRelationships, scopes } }
+    );
+  }
+  
+  return context.record;
+}

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

@@ -0,0 +1,56 @@
+/**
+ * PATCH RELATIONSHIP
+ * Completely replaces a relationship
+ * PATCH /api/articles/1/relationships/author
+ * 
+ * @param {string} id - The ID of the resource
+ * @param {string} relationshipName - The name of the relationship
+ * @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 }) {
+  context.method = 'patchRelationship';
+  context.id = params.id;
+  context.relationshipName = params.relationshipName;
+
+  // Transaction handling
+  context.transaction = params.transaction || 
+    (helpers.newTransaction && !params.transaction ? await helpers.newTransaction() : null);
+  context.shouldCommit = !params.transaction && !!context.transaction;
+  context.db = context.transaction || api.knex.instance
+
+  try {
+    // Check permissions
+    await runHooks('checkPermissions');
+    await runHooks('checkPermissionsPatchRelationship');
+
+    // Reuse existing patch with relationship data
+    await scope.patch({
+      id: context.id,
+      inputRecord: {
+        data: {
+          type: scopeName,
+          id: context.id,
+          relationships: {
+            [params.relationshipName]: { data: params.relationshipData }
+          }
+        }
+      },
+      transaction: context.transaction,
+      simplified: false,
+      isTransport: params.isTransport
+    });
+
+    await runHooks('finish');
+    await runHooks('finishPatchRelationship');
+
+    if (context.shouldCommit) {
+      await context.transaction.commit();
+    }
+
+    return; // 204 No Content
+
+  } catch (error) {
+    await handleWriteMethodError(error, context, 'PATCH_RELATIONSHIP', scopeName, log);
+  }
+}