Common API Examples

This page provides unified examples showing how to perform common operations across all three Buzzy API approaches:

BuzzyFrameAPI (Async) - Client-side JavaScript API for Code Widgets
REST API - Direct HTTP API calls for external integrations
Node.js API Client - Convenience wrapper for Node.js applications

Each example shows the same operation implemented in all three formats, making it easy to choose the right approach for your use case.

Authentication Setup

Before using any of the APIs, you need to authenticate and obtain the necessary credentials.

BuzzyFrameAPI (Async)

const buzzyFrameAPI = new BuzzyFrameAPI();
await buzzyFrameAPI.initialise();

REST API

// Login to get auth credentials
const loginResponse = await fetch('https://your-buzzy-instance.com/api/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: '[email protected]',
    password: 'password'
  })
});
const { authToken, userId } = await loginResponse.json();

Node.js API Client

import { login } from 'buzzy-api-nodejs';

const auth = await login({
  url: 'https://your-buzzy-instance.com',
  email: '[email protected]', 
  password: 'password'
});
const { token: authToken, userId } = auth;

Contact Management CRUD Operations

Create a New Contact

BuzzyFrameAPI (Async)

const result = await buzzyFrameAPI.insertMicroappRow({
  body: {
    microAppID: "contacts-datatable-id",
    rowData: {
      name: "John Smith",
      email: "[email protected]",
      phone: "+1-555-0123",
      company: "Acme Corp"
    }
  }
});
console.log("Created contact with ID:", result.rowID);

REST API

const response = await fetch('https://your-buzzy-instance.com/api/insertmicroapprow', {
  method: 'POST',
  headers: {
    'X-Auth-Token': authToken,
    'X-User-Id': userId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    microAppID: "contacts-datatable-id",
    rowData: {
      name: "John Smith",
      email: "[email protected]", 
      phone: "+1-555-0123",
      company: "Acme Corp"
    }
  })
});
const result = await response.json();
console.log("Created contact:", result);

Node.js API Client

import { insertMicroAppRow } from 'buzzy-api-nodejs';

const result = await insertMicroAppRow({
  microAppID: "contacts-datatable-id",
  authToken,
  userId,
  url: 'https://your-buzzy-instance.com',
  rowData: {
    name: "John Smith",
    email: "[email protected]",
    phone: "+1-555-0123", 
    company: "Acme Corp"
  }
});
console.log("Created contact with ID:", result.rowID);

Read/Fetch Contacts

BuzzyFrameAPI (Async)

const contacts = await buzzyFrameAPI.fetchDataTableRows({
  microAppID: "contacts-datatable-id"
});
console.log("Found contacts:", contacts);

REST API

const response = await fetch('https://your-buzzy-instance.com/api/microappdata', {
  method: 'POST',
  headers: {
    'X-Auth-Token': authToken,
    'X-User-Id': userId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    microAppID: "contacts-datatable-id"
  })
});
const contacts = await response.json();
console.log("Found contacts:", contacts);

Node.js API Client

import { getMicroAppData } from 'buzzy-api-nodejs';

const contacts = await getMicroAppData({
  microAppID: "contacts-datatable-id",
  authToken,
  userId,
  url: 'https://your-buzzy-instance.com'
});
console.log("Found contacts:", contacts);

Update a Contact

BuzzyFrameAPI (Async)

const result = await buzzyFrameAPI.updateMicroappRow({
  body: {
    rowID: "contact-row-id",
    rowData: {
      phone: "+1-555-9999",
      company: "New Company Inc"
    }
  }
});
console.log("Update result:", result.body);

REST API

const response = await fetch('https://your-buzzy-instance.com/api/updatemicroapprow', {
  method: 'POST',
  headers: {
    'X-Auth-Token': authToken,
    'X-User-Id': userId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    rowID: "contact-row-id",
    rowData: {
      phone: "+1-555-9999",
      company: "New Company Inc"
    }
  })
});
const result = await response.json();
console.log("Update result:", result);

Node.js API Client

import { updateMicroAppDataRow } from 'buzzy-api-nodejs';

const result = await updateMicroAppDataRow({
  rowID: "contact-row-id",
  authToken,
  userId,
  url: 'https://your-buzzy-instance.com',
  rowData: {
    phone: "+1-555-9999",
    company: "New Company Inc"
  }
});
console.log("Update successful:", result);

Delete a Contact

BuzzyFrameAPI (Async)

await buzzyFrameAPI.removeMicroappRow({
  rowID: "contact-row-id"
});
console.log("Contact deleted");

REST API

const response = await fetch('https://your-buzzy-instance.com/api/removemicroapprow', {
  method: 'POST',
  headers: {
    'X-Auth-Token': authToken,
    'X-User-Id': userId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    rowID: "contact-row-id"
  })
});
const result = await response.json();
console.log("Delete result:", result);

Node.js API Client

import { removeMicroAppRow } from 'buzzy-api-nodejs';

const result = await removeMicroAppRow(
  "contact-row-id",
  authToken,
  userId,
  'https://your-buzzy-instance.com'
);
console.log("Contact deleted:", result);

Data Filtering and Pagination

Filter Contacts by Company

BuzzyFrameAPI (Async)

const filteredContacts = await buzzyFrameAPI.fetchDataTableRows({
  microAppID: "contacts-datatable-id",
  viewFilters: [
    { company: "Acme Corp" }
  ]
});
console.log("Acme Corp contacts:", filteredContacts);

REST API

const response = await fetch('https://your-buzzy-instance.com/api/microappdata', {
  method: 'POST',
  headers: {
    'X-Auth-Token': authToken,
    'X-User-Id': userId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    microAppID: "contacts-datatable-id",
    optViewFilters: [
      { company: "Acme Corp" }
    ]
  })
});
const filteredContacts = await response.json();
console.log("Acme Corp contacts:", filteredContacts);

Node.js API Client

import { getMicroAppData } from 'buzzy-api-nodejs';

const filteredContacts = await getMicroAppData({
  microAppID: "contacts-datatable-id",
  authToken,
  userId,
  url: 'https://your-buzzy-instance.com',
  optViewFilters: [
    { company: "Acme Corp" }
  ]
});
console.log("Acme Corp contacts:", filteredContacts);

Paginated Results

BuzzyFrameAPI (Async)

const paginatedContacts = await buzzyFrameAPI.fetchDataTableRows({
  microAppID: "contacts-datatable-id",
  queryOptions: [{
    resourceID: "contacts-datatable-id",
    limit: 10,
    skip: 20
  }]
});
console.log("Page 3 contacts (10 per page):", paginatedContacts);

REST API

const response = await fetch('https://your-buzzy-instance.com/api/microappdata', {
  method: 'POST',
  headers: {
    'X-Auth-Token': authToken,
    'X-User-Id': userId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    microAppID: "contacts-datatable-id",
    searchFilter: [{
      resourceID: "contacts-datatable-id",
      limit: 10,
      skip: 20
    }]
  })
});
const paginatedContacts = await response.json();
console.log("Page 3 contacts (10 per page):", paginatedContacts);

Node.js API Client

import { getMicroAppData } from 'buzzy-api-nodejs';

const paginatedContacts = await getMicroAppData({
  microAppID: "contacts-datatable-id",
  authToken,
  userId,
  url: 'https://your-buzzy-instance.com',
  searchFilter: [{
    resourceID: "contacts-datatable-id", 
    limit: 10,
    skip: 20
  }]
});
console.log("Page 3 contacts (10 per page):", paginatedContacts);

Organization and Team Management

Create an Organization

BuzzyFrameAPI (Async)

// Note: Organization management is not available in BuzzyFrameAPI
// Use REST API or Node.js client for organization operations
console.log("Organization management not available in BuzzyFrameAPI");

REST API

const response = await fetch('https://your-buzzy-instance.com/api/insertorganization', {
  method: 'POST',
  headers: {
    'X-Auth-Token': authToken,
    'X-User-Id': userId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    organizationInfo: {
      name: "Acme Corporation",
      description: "Leading provider of innovative solutions"
    }
  })
});
const result = await response.json();
console.log("Created organization:", result);

Node.js API Client

import { insertOrganization } from 'buzzy-api-nodejs';

const result = await insertOrganization({
  authToken,
  userId,
  url: 'https://your-buzzy-instance.com',
  organizationInfo: {
    name: "Acme Corporation",
    description: "Leading provider of innovative solutions"
  }
});
console.log("Created organization:", result);

Create a Team

BuzzyFrameAPI (Async)

// Note: Team management is not available in BuzzyFrameAPI
// Use REST API or Node.js client for team operations
console.log("Team management not available in BuzzyFrameAPI");

REST API

const response = await fetch('https://your-buzzy-instance.com/api/insertteam', {
  method: 'POST',
  headers: {
    'X-Auth-Token': authToken,
    'X-User-Id': userId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    teamInfo: {
      name: "Sales Team",
      organizationId: "organization-id"
    },
    adminID: userId
  })
});
const result = await response.json();
console.log("Created team:", result);

Node.js API Client

import { insertTeam } from 'buzzy-api-nodejs';

const result = await insertTeam({
  authToken,
  userId,
  url: 'https://your-buzzy-instance.com',
  teamInfo: {
    name: "Sales Team",
    organizationId: "organization-id"
  },
  adminID: userId
});
console.log("Created team:", result);

Add Team Members

BuzzyFrameAPI (Async)

// Note: Team member management is not available in BuzzyFrameAPI
// Use REST API or Node.js client for team member operations
console.log("Team member management not available in BuzzyFrameAPI");

REST API

const response = await fetch('https://your-buzzy-instance.com/api/insertteammembers', {
  method: 'POST',
  headers: {
    'X-Auth-Token': authToken,
    'X-User-Id': userId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    teamIDs: ["team-id"],
    emails: ["[email protected]", "[email protected]"],
    targetRoute: "app"
  })
});
const result = await response.json();
console.log("Added team members:", result);

Node.js API Client

import { insertTeamMembers } from 'buzzy-api-nodejs';

const result = await insertTeamMembers({
  authToken,
  userId,
  url: 'https://your-buzzy-instance.com',
  teamIDs: ["team-id"],
  emails: ["[email protected]", "[email protected]"],
  targetRoute: "app"
});
console.log("Added team members:", result);

Linked Table Field Operations

Create Record with Linked Table Fields

BuzzyFrameAPI (Async)

const result = await buzzyFrameAPI.insertMicroappRow({
  body: {
    microAppID: "projects-datatable-id",
    rowData: {
      projectName: "Website Redesign",
      assignedUser: {
        crossAppRowID: "user-row-id",
        value: {
          label: "name",
          value: "John Smith"
        }
      },
      clientOrganization: {
        crossAppRowID: "org-row-id",
        value: {
          label: "organizationName", 
          value: "Acme Corp"
        }
      }
    }
  }
});
console.log("Created project with linked fields:", result.rowID);

REST API

const response = await fetch('https://your-buzzy-instance.com/api/insertmicroapprow', {
  method: 'POST',
  headers: {
    'X-Auth-Token': authToken,
    'X-User-Id': userId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    microAppID: "projects-datatable-id",
    rowData: {
      projectName: "Website Redesign",
      assignedUser: {
        crossAppRowID: "user-row-id",
        value: {
          label: "name",
          value: "John Smith"
        }
      },
      clientOrganization: {
        crossAppRowID: "org-row-id",
        value: {
          label: "organizationName",
          value: "Acme Corp"
        }
      }
    }
  })
});
const result = await response.json();
console.log("Created project with linked fields:", result);

Node.js API Client

import { insertMicroAppRow } from 'buzzy-api-nodejs';

const result = await insertMicroAppRow({
  microAppID: "projects-datatable-id",
  authToken,
  userId,
  url: 'https://your-buzzy-instance.com',
  rowData: {
    projectName: "Website Redesign",
    assignedUser: {
      crossAppRowID: "user-row-id",
      value: {
        label: "name",
        value: "John Smith"
      }
    },
    clientOrganization: {
      crossAppRowID: "org-row-id",
      value: {
        label: "organizationName",
        value: "Acme Corp"
      }
    }
  }
});
console.log("Created project with linked fields:", result);

Error Handling Patterns

Handling Authentication Errors

BuzzyFrameAPI (Async)

try {
  const result = await buzzyFrameAPI.insertMicroappRow({
    body: {
      microAppID: "contacts-datatable-id",
      rowData: { name: "Test Contact" }
    }
  });
  console.log("Success:", result);
} catch (error) {
  if (error.message.includes('authentication')) {
    console.error("Authentication failed - please re-initialize BuzzyFrameAPI");
  } else {
    console.error("Operation failed:", error.message);
  }
}

REST API

try {
  const response = await fetch('https://your-buzzy-instance.com/api/insertmicroapprow', {
    method: 'POST',
    headers: {
      'X-Auth-Token': authToken,
      'X-User-Id': userId,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      microAppID: "contacts-datatable-id",
      rowData: { name: "Test Contact" }
    })
  });
  
  if (!response.ok) {
    if (response.status === 401) {
      throw new Error("Authentication failed - token may be expired");
    }
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }
  
  const result = await response.json();
  console.log("Success:", result);
} catch (error) {
  console.error("Operation failed:", error.message);
}

Node.js API Client

import { insertMicroAppRow } from 'buzzy-api-nodejs';

try {
  const result = await insertMicroAppRow({
    microAppID: "contacts-datatable-id",
    authToken,
    userId,
    url: 'https://your-buzzy-instance.com',
    rowData: { name: "Test Contact" }
  });
  console.log("Success:", result);
} catch (error) {
  if (error.response?.status === 401) {
    console.error("Authentication failed - please login again");
  } else if (error.response?.status === 404) {
    console.error("Datatable not found - check microAppID");
  } else {
    console.error("Operation failed:", error.message);
  }
}

File and Image Management (MicroAppChild)

Create File Attachment

BuzzyFrameAPI (Async)

await buzzyFrameAPI.createMicroappChild({
  microAppResourceID: "datatable-id",
  appID: "parent-row-id",
  fieldID: "attachment-field-id",
  content: {
    url: "https://example.com/file.pdf",
    filename: "document.pdf",
    size: 1024000,
    type: "application/pdf",
    expiredAt: Date.now() + (7 * 24 * 60 * 60 * 1000) // 7 days
  }
});
console.log("File attached to record");

REST API

const response = await fetch('https://your-buzzy-instance.com/api/microappchild/create', {
  method: 'POST',
  headers: {
    'X-Auth-Token': authToken,
    'X-User-Id': userId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    microAppResourceID: "datatable-id",
    appID: "parent-row-id",
    fieldID: "attachment-field-id",
    content: {
      url: "https://example.com/file.pdf",
      filename: "document.pdf",
      size: 1024000,
      type: "application/pdf",
      expiredAt: Date.now() + (7 * 24 * 60 * 60 * 1000)
    }
  })
});
const result = await response.json();
console.log("File attached:", result);

Node.js API Client

import { createMicroAppChild } from 'buzzy-api-nodejs';

const result = await createMicroAppChild({
  authToken,
  userId,
  url: 'https://your-buzzy-instance.com',
  microAppResourceID: "datatable-id",
  appID: "parent-row-id",
  fieldID: "attachment-field-id",
  content: {
    url: "https://example.com/file.pdf",
    filename: "document.pdf",
    size: 1024000,
    type: "application/pdf",
    expiredAt: Date.now() + (7 * 24 * 60 * 60 * 1000)
  }
});
console.log("File attached:", result);

List File Attachments

BuzzyFrameAPI (Async)

const attachments = await buzzyFrameAPI.getChildItemsByField({
  appID: "parent-row-id",
  fieldID: "attachment-field-id"
});
console.log("Found attachments:", attachments);

REST API

const response = await fetch('https://your-buzzy-instance.com/api/microappchild/list?appID=parent-row-id&fieldID=attachment-field-id', {
  method: 'GET',
  headers: {
    'X-Auth-Token': authToken,
    'X-User-Id': userId,
    'Content-Type': 'application/json'
  }
});
const result = await response.json();
console.log("Found attachments:", result.body.childItems);

Node.js API Client

import { getChildItemsByField } from 'buzzy-api-nodejs';

const attachments = await getChildItemsByField({
  authToken,
  userId,
  url: 'https://your-buzzy-instance.com',
  appID: "parent-row-id",
  fieldID: "attachment-field-id"
});
console.log("Found attachments:", attachments);

Update File Attachment

BuzzyFrameAPI (Async)

await buzzyFrameAPI.updateMicroappChild({
  childID: "attachment-id",
  content: {
    url: "https://example.com/updated-file.pdf",
    filename: "updated-document.pdf",
    expiredAt: Date.now() + (14 * 24 * 60 * 60 * 1000) // 14 days
  }
});
console.log("File attachment updated");

REST API

const response = await fetch('https://your-buzzy-instance.com/api/microappchild/update', {
  method: 'POST',
  headers: {
    'X-Auth-Token': authToken,
    'X-User-Id': userId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    childID: "attachment-id",
    content: {
      url: "https://example.com/updated-file.pdf",
      filename: "updated-document.pdf",
      expiredAt: Date.now() + (14 * 24 * 60 * 60 * 1000)
    }
  })
});
const result = await response.json();
console.log("File updated:", result);

Node.js API Client

import { updateMicroAppChild } from 'buzzy-api-nodejs';

const result = await updateMicroAppChild({
  authToken,
  userId,
  url: 'https://your-buzzy-instance.com',
  childID: "attachment-id",
  content: {
    url: "https://example.com/updated-file.pdf",
    filename: "updated-document.pdf",
    expiredAt: Date.now() + (14 * 24 * 60 * 60 * 1000)
  }
});
console.log("File updated:", result);

Delete File Attachment

BuzzyFrameAPI (Async)

await buzzyFrameAPI.removeMicroappChild({
  childID: "attachment-id"
});
console.log("File attachment deleted");

REST API

const response = await fetch('https://your-buzzy-instance.com/api/microappchild/delete', {
  method: 'POST',
  headers: {
    'X-Auth-Token': authToken,
    'X-User-Id': userId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    childID: "attachment-id"
  })
});
const result = await response.json();
console.log("File deleted:", result);

Node.js API Client

import { removeMicroAppChild } from 'buzzy-api-nodejs';

const result = await removeMicroAppChild({
  authToken,
  userId,
  url: 'https://your-buzzy-instance.com',
  childID: "attachment-id"
});
console.log("File deleted:", result);

Authentication Setup

BuzzyFrameAPI (Async)

REST API

Node.js API Client

Contact Management CRUD Operations

Create a New Contact

Read/Fetch Contacts

Update a Contact

Delete a Contact

Data Filtering and Pagination

Filter Contacts by Company

Paginated Results

Organization and Team Management

Create an Organization

Create a Team

Add Team Members

Linked Table Field Operations

Create Record with Linked Table Fields

Error Handling Patterns

Handling Authentication Errors

File and Image Management (MicroAppChild)

Create File Attachment

List File Attachments

Update File Attachment

Delete File Attachment

See Also