List

The list method retrieves multiple records from a collection with support for filtering and pagination.

Configuration Example

# spec.yml
name: Collection Name
methods:
  list:
    filterFields:
      - email
      - firstName
      - lastName
    parametersSchema:
      type: object
      properties:
        includeArchived:
          type: boolean
          default: false

Properties:

parametersSchema (DataSchema): Schema for the additional parameters
filterFields (array): Fields that can be used for filtering of the results.

Implementation Examples

REST API Mapping Implementation (Recommended)

File: list.rest.yml

path: /contacts
method: GET
requestMapping:
  query:
    limit: 100
    offset: { $var: $.cursor }
    email: { $var: $.filter.email }
    first_name: { $var: $.filter.firstName }
    last_name: { $var: $.filter.lastName }
    include_archived: { $var: $.parameters.includeArchived }
responseMapping:
  records: { $var: response.data.contacts }
  cursor: |
    {
      $cond: [
        { $var: response.data.hasMore },
        { $string: { $sum: [{ $number: { $var: $.cursor } }, 100] } },
        null
      ]
    }

JavaScript Implementation

File: list.js

export default async function list({ apiClient, filter, cursor, parameters }) {
  const queryParams = {
    limit: 100,
    offset: cursor || 0,
    includeArchived: parameters?.includeArchived || false,
  }

  // Apply filters
  if (filter?.email) {
    queryParams.email = filter.email
  }
  if (filter?.firstName) {
    queryParams.first_name = filter.firstName
  }
  if (filter?.lastName) {
    queryParams.last_name = filter.lastName
  }

  const response = await apiClient.get("/contacts", { params: queryParams })

  return {
    records: response.data.contacts,
    cursor: response.data.hasMore
      ? String(queryParams.offset + 100)
      : undefined,
  }
}

Input

Property	Type	Description
`filter`	object	Filter criteria based on configured filterFields
`cursor`	string	Pagination cursor from previous request
`credentials`	object	Authentication credentials
`parameters`	object	Method-specific parameters

Return Value

Property	Type	Description
`records`	array	Array of records in API format (before fieldsFromApi)
`cursor`	string	Cursor for next page (optional)
`drilldowns`	array	Additional requests to fetch related data (optional)

Drilldowns

The list method supports drilldowns for fetching nested or related data. This is useful for scenarios like fetching files from multiple folders or tasks across different projects.

// Example: Fetching files from folders
module.exports = async ({ filter, cursor, parameters }) => {
  if (!cursor && filter?.parentFolderId === "root") {
    // First, get all folders
    const folders = await makeApiRequest({
      method: "GET",
      path: "/api/folders",
      credentials,
    })

    // Return folders with drilldowns for their files
    return {
      records: folders.data,
      drilldowns: folders.data.map((folder) => ({
        parameters: { recursive: true },
        filter: {
          type: "file",
          parentFolderId: folder.id,
        },
      })),
    }
  }

  // Regular file listing
  const response = await makeApiRequest({
    method: "GET",
    path: "/api/files",
    query: { folderId: filter?.parentFolderId },
    credentials,
  })

  return {
    records: response.data,
  }
}

Drilldown Structure

{
  "drilldowns": [
    {
      "parameters": { "recursive": true },
      "filter": {
        "type": "file",
        "parentFolderId": "123"
      }
    }
  ]
}