The fieldsFromApi method transforms raw API responses into the format defined by your collection's fieldsSchema. This method is called automatically when retrieving records from the external API.

Implementation Examples

Mapping Implementation (Recommended)

File: fields-from-api.map.yml

id: { $var: fields.contact_id }
email: { $var: fields.email_address }
firstName: { $var: fields.first_name }
lastName: { $var: fields.last_name }
fullName:
  $join: [" ", [{ $var: fields.first_name }, { $var: fields.last_name }]]
createdAt:
  $cond:
    - { $var: parameters.includeTimestamps }
    - { $var: fields.created_at }
    - null
updatedAt:
  $cond:
    - { $var: parameters.includeTimestamps }
    - { $var: fields.updated_at }
    - null

JavaScript Implementation

File: fields-from-api.js

export default async function fieldsFromApi({ fields, parameters }) {
  // Transform API response to match fieldsSchema
  const transformed = {
    id: fields.contact_id,
    email: fields.email_address,
    firstName: fields.first_name,
    lastName: fields.last_name,
    // Add computed fields
    fullName: `${fields.first_name} ${fields.last_name}`,
  }

  // Add optional fields based on parameters
  if (parameters?.includeTimestamps) {
    transformed.createdAt = fields.created_at
    transformed.updatedAt = fields.updated_at
  }

  return transformed
}

Input

Property	Type	Description
`fields`	object	Raw fields from the API response
`parameters`	object	Collection parameters

Return Value

The method should return an object matching the collection's fieldsSchema.

Example

// API returns:
{
  "contact_id": "123",
  "email_address": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "created_at": "2024-01-01T00:00:00Z"
}

// fieldsFromApi transforms to:
{
  "id": "123",
  "email": "john@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "fullName": "John Doe"
}