Replication strategy

This is the official documentation of the @forestadmin/agent Node.js agent.

The idea behind data sources using the "replication" strategy is to maintain a copy of the data from the target API in an internal cache that is under the control of your agent.



No need to implement any query translation logic.


No need to make network calls to the target API synchronously.


Charts, filtering, search is provided out of the box.


You can implement any logic you want to fetch the data from the target API.


Any bad state can be recovered from by reconstructing the replica from scratch in the background.

Minimal example

This example shows how to create a custom data source using the "replication" strategy on {JSON} Placeholder ↗, a free API that returns read-only fake data.

In this trivial example, records will be fetched from the target API when the agent first starts, never to be updated again.


The most stripped-down implementation of a data source using the "replication" strategy is simply providing a function that returns a list of entries to be imported.

const { createReplicaDataSource } = require('@forestadmin/datasource-replica');
const axios = require('axios');

// Create the data source
const myCustomDataSource = createReplicaDataSource({
  pullDumpHandler: async () => {
    const url = '';
    const collections = ['posts', 'comments', 'albums', 'photos', 'users'];
    const entries = [];

    for (const collection of collections) {
      const response = await axios.get(`${url}/${collection}`);
      entries.push( => ({ collection, record })));

    return { more: false, entries };

// Register the data source with the agent


This minimal example is a good starting point to understand the selling points of the replication strategy, however, strong limitations remain and you may need to implement more logic to tackle them.


Needs to dump all records at each startup

Empty collections cannot be imported and foreign keys are not detected

Provide a schema

The data is never updated

Implement updates

The data is readonly

Implement write handlers

Records from API may contain nested fields and arrays

Last updated