Common API Examples

This page shows the same common operations across the three main Buzzy API styles:

• BuzzyFrameAPI (Async) for client-side code widgets

• REST API for direct HTTP integrations

• Node.js API Client for server-side JavaScript wrappers

Use the REST API pages as the canonical reference for shared row semantics:

• Row Metadata and Relationships

• microappdata

• microappdata/row

Authentication Setup

BuzzyFrameAPI (Async)

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

REST API

const loginResponse = await fetch('https://your-buzzy-instance.com/api/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: '[e-mail]',
    password: 'password'
  })
});

const loginResult = await loginResponse.json();
const { authToken, userId } = loginResult.data;

Node.js API Client

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

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

const { token: authToken, userId } = auth;

Token Handling

REST API

Use the authToken and userId returned from login on authenticated requests:

const headers = {
  'X-Auth-Token': authToken,
  'X-User-Id': userId,
  'Content-Type': 'application/json'
};

Node.js API Client

Pass the same values as method arguments:

const commonAuth = {
  authToken,
  userId,
  url: 'https://your-buzzy-instance.com'
};

Logout

REST API

await fetch('https://your-buzzy-instance.com/api/logout', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ authToken, userId })
});

Node.js API Client

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

await logout({
  authToken,
  userId,
  url: 'https://your-buzzy-instance.com'
});

Create a New Contact

BuzzyFrameAPI (Async)

const result = await buzzyFrameAPI.insertMicroappRow({
  body: {
    microAppID: 'contacts-datatable-id',
    rowData: {
      name: 'John Smith',
      email: '[e-mail]',
      phone: '[phone]',
      company: 'Acme Corp'
    }
  }
});

console.log(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: '[e-mail]',
      phone: '[phone]',
      company: 'Acme Corp'
    }
  })
});

const result = await response.json();
console.log(result.rowID);

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: '[e-mail]',
    phone: '[phone]',
    company: 'Acme Corp'
  }
});

console.log(result.rowID);

Read/Fetch Contacts

BuzzyFrameAPI (Async)

const contacts = await buzzyFrameAPI.fetchDataTableRows({
  microAppID: 'contacts-datatable-id'
});

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();

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'
});

Update a Contact

BuzzyFrameAPI (Async)

await buzzyFrameAPI.updateMicroappRow({
  body: {
    rowID: 'contact-row-id',
    rowData: {
      phone: '[phone]',
      company: 'New Company Inc'
    }
  }
});

REST API

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: '[phone]',
      company: 'New Company Inc'
    }
  })
});

Node.js API Client

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

await updateMicroAppDataRow({
  rowID: 'contact-row-id',
  authToken,
  userId,
  url: 'https://your-buzzy-instance.com',
  rowData: {
    phone: '[phone]',
    company: 'New Company Inc'
  }
});

Delete a Contact

BuzzyFrameAPI (Async)

await buzzyFrameAPI.removeMicroappRow({
  rowID: 'contact-row-id'
});

REST API

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'
  })
});

Node.js API Client

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

await removeMicroAppRow(
  'contact-row-id',
  authToken,
  userId,
  'https://your-buzzy-instance.com'
);

Metadata-Aware Row Access

Rows returned by Buzzy can include business fields and system-managed metadata such as _id, userID, submitted, clientSubmitted, and embeddingRowID.

See Row Metadata and Relationships for the canonical definition.

REST API

const response = await fetch('https://your-buzzy-instance.com/api/microappdata/row', {
  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(result.currentRow._id);
console.log(result.currentRow.submitted);
console.log(result.currentRow.clientSubmitted);

Node.js API Client

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

const row = await getMicroAppDataRow({
  rowID: 'contact-row-id',
  authToken,
  userId,
  url: 'https://your-buzzy-instance.com'
});

console.log(row.currentRow._id);
console.log(row.currentRow.submitted);

Working with embeddingRowID

Use embeddingRowID for sub-table parent-child relationships.

Create a Child Row

BuzzyFrameAPI (Async)

await buzzyFrameAPI.insertMicroappRow({
  body: {
    microAppID: 'invoice-lines-datatable-id',
    embeddingRowID: 'invoice-row-id',
    rowData: {
      product: 'Widget',
      quantity: 2
    }
  }
});

REST API

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: 'invoice-lines-datatable-id',
    embeddingRowID: 'invoice-row-id',
    rowData: {
      product: 'Widget',
      quantity: 2
    }
  })
});

Node.js API Client

await insertMicroAppRow({
  microAppID: 'invoice-lines-datatable-id',
  embeddingRowID: 'invoice-row-id',
  authToken,
  userId,
  url: 'https://your-buzzy-instance.com',
  rowData: {
    product: 'Widget',
    quantity: 2
  }
});

Read Child Rows for One Parent

BuzzyFrameAPI (Async)

const invoiceLines = await buzzyFrameAPI.fetchDataTableRows({
  microAppID: 'invoice-lines-datatable-id',
  embeddingRowID: 'invoice-row-id'
});

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: 'invoice-lines-datatable-id',
    optViewFilters: [
      {
        embeddingRowID: 'invoice-row-id'
      }
    ]
  })
});

const invoiceLines = await response.json();

Node.js API Client

const invoiceLines = await getMicroAppData({
  microAppID: 'invoice-lines-datatable-id',
  authToken,
  userId,
  url: 'https://your-buzzy-instance.com',
  optViewFilters: [
    {
      embeddingRowID: 'invoice-row-id'
    }
  ]
});

Linked-Table Field Example

Use linked-table fields when you want to reference a row in another Datatable. This is different from embeddingRowID.

REST API

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-table-id',
    rowData: {
      assignedUser: {
        crossAppRowID: 'user-row-id',
        value: {
          label: 'name',
          value: 'Jane Doe'
        }
      }
    }
  })
});

See microappdata/row for the response shape.

See Also

• Row Metadata and Relationships

• microappdata

• microappdata/row

• BuzzyFrameAPI Documentation

• Node.js API Client