> For the complete documentation index, see [llms.txt](https://docs.buzzy.buzz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buzzy.buzz/developing-and-extending-buzzy/buzzy-rest-api/rest-api/common-api-examples.md).

# 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](/developing-and-extending-buzzy/buzzy-rest-api/rest-api/microapp-data-operations/row-metadata-and-relationships.md)
* [microappdata](/developing-and-extending-buzzy/buzzy-rest-api/rest-api/microapp-data-operations/microappdata.md)
* [microappdata/row](/developing-and-extending-buzzy/buzzy-rest-api/rest-api/microapp-data-operations/microappdata-row.md)

## Authentication Setup

### BuzzyFrameAPI (Async)

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

### REST API

```javascript
const loginResponse = await fetch('https://your-buzzy-instance.com/api/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'password'
  })
});

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

### Node.js API Client

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

const auth = await login({
  url: 'https://your-buzzy-instance.com',
  email: 'user@example.com',
  password: 'password'
});

const { token: authToken, userId } = auth;
```

## Token Handling

### REST API

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

```javascript
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:

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

## Logout

### REST API

```javascript
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

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

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

## Create a New Contact

### BuzzyFrameAPI (Async)

```javascript
const result = await buzzyFrameAPI.insertMicroappRow({
  body: {
    microAppID: 'contacts-datatable-id',
    rowData: {
      name: 'John Smith',
      email: 'john@example.com',
      phone: '+1-555-0123',
      company: 'Acme Corp'
    }
  }
});

console.log(result.rowID);
```

### REST API

```javascript
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: 'john@example.com',
      phone: '+1-555-0123',
      company: 'Acme Corp'
    }
  })
});

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

### Node.js API Client

```javascript
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: 'john@example.com',
    phone: '+1-555-0123',
    company: 'Acme Corp'
  }
});

console.log(result.rowID);
```

## Read/Fetch Contacts

### BuzzyFrameAPI (Async)

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

### REST API

```javascript
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

```javascript
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)

```javascript
await buzzyFrameAPI.updateMicroappRow({
  body: {
    rowID: 'contact-row-id',
    rowData: {
      phone: '+1-555-9999',
      company: 'New Company Inc'
    }
  }
});
```

### REST API

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

### Node.js API Client

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

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

## Delete a Contact

### BuzzyFrameAPI (Async)

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

### REST API

```javascript
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

```javascript
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](/developing-and-extending-buzzy/buzzy-rest-api/rest-api/microapp-data-operations/row-metadata-and-relationships.md) for the canonical definition.

### REST API

```javascript
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

```javascript
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)

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

#### REST API

```javascript
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

```javascript
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)

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

#### REST API

```javascript
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

```javascript
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

```javascript
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](/developing-and-extending-buzzy/buzzy-rest-api/rest-api/microapp-data-operations/microappdata-row.md#linkedtable-crossapp-row-field-example) for the response shape.

## See Also

* [Row Metadata and Relationships](/developing-and-extending-buzzy/buzzy-rest-api/rest-api/microapp-data-operations/row-metadata-and-relationships.md)
* [microappdata](/developing-and-extending-buzzy/buzzy-rest-api/rest-api/microapp-data-operations/microappdata.md)
* [microappdata/row](/developing-and-extending-buzzy/buzzy-rest-api/rest-api/microapp-data-operations/microappdata-row.md)
* [BuzzyFrameAPI Documentation](/the-building-blocks/code-widget-custom-code/new-async-api-+-react-html-components.md)
* [Node.js API Client](/developing-and-extending-buzzy/buzzy-rest-api/nodejs-api-client.md)