Skip to main content
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

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

PropertyTypeDescription
filterobjectFilter criteria based on configured filterFields
cursorstringPagination cursor from previous request
credentialsobjectAuthentication credentials
parametersobjectMethod-specific parameters

​
Return Value

PropertyTypeDescription
recordsarrayArray of records in API format (before fieldsFromApi)
cursorstringCursor for next page (optional)
drilldownsarrayAdditional 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"
      }
    }
  ]
}