Tutorial: Simple app

In the tutorial we will implement the simplest app with token authentication. We will use NodeJS and Express framework, but you can use any other programming language. Find source code repository here: https://gitlab.com/fibery-community/integration-sample-apps To create simple app you need to implement following Custom App: REST Endpoints:

getting app information: GET /
validate account: POST /validate
getting synchronizer configuration: POST /api/v1/synchronizer/config
getting schema: POST /api/v1/synchronizer/schema
fetching data POST /api/v1/synchronizer/data

Let’s implement them one by one. But first let’s define dataset:

const users = {
  token1: {
    name: `Dad Sholler`,
    data: {
      flower: [
        {id: `47fd45cf-5a07-40aa-9ee4-a4258832154a`, name: `Rose`},
        {id: `4f3afc75-2fb9-4ff8-b26f-ab4bf2f470a3`, name: `Lily`},
        {id: `d7525fc1-1979-4cfb-ba32-0dfab9280b24`, name: `Tulip`},
      ],
      regionPrice: [
        {
          id: `56c50696-1d9f-4e4d-9678-448017d25474`,
          flowerId: `d7525fc1-1979-4cfb-ba32-0dfab9280b24`,
          price: 10,
          name: `Eastern Europe`,
        },
        {
          id: `503e5efb-7650-4c3a-85e9-f4ebc23adfd5`,
          name: `Western Europe`,
          flowerId: `d7525fc1-1979-4cfb-ba32-0dfab9280b24`,
          price: 15,
        },
        {
          id: `87ccd5ef-ed3f-49db-9bcc-c9d1daf91744`,
          name: `Eastern Europe`,
          price: 20,
          flowerId: `47fd45cf-5a07-40aa-9ee4-a4258832154a`,
        },
      ],
    },
  },
  token2: {
    name: `Ben Dreamer`,
    data: {
      flower: [
        {id: `4f3afc75-2fb9-4ff8-b26f-ab4bf2f470a3`, name: `Lily`},
        {id: `d7525fc1-1979-4cfb-ba32-0dfab9280b24`, name: `Tulip`},
      ],
      regionPrice: [
        {
          id: `c3352e8c-e62c-4e26-9a8b-852c1a3d2435`,
          flowerId: `d7525fc1-1979-4cfb-ba32-0dfab9280b24`,
          price: 10,
          name: `East Coast`,
        },
        {
          id: `7a581588-d5fc-46aa-a084-8e2b28f3d6e5`,
          name: `West Coast`,
          flowerId: `d7525fc1-1979-4cfb-ba32-0dfab9280b24`,
          price: 15,
        },
        {
          id: `6e510195-41e3-499b-9a76-9ad928720882`,
          name: `Asia`,
          price: 20,
          flowerId: `4f3afc75-2fb9-4ff8-b26f-ab4bf2f470a3`,
        },
      ],
    },
  },
};

Getting app information

App information should have the structure described in App configuration. Let’s implement it. We can see that the app require token authentication and responsible for data synchronization.

app.get(`/`, (req, res) => {
  res.json({
    id: 'integration-sample-app',
    name: 'Integration Sample App',
    version: `1.0.0`,
    type: 'crunch',
    description: 'Integration sample app.',
    authentication: [
      {
        description: 'Provide Token',
        name: 'Token Authentication',
        id: 'token',
        fields: [
          {
            type: 'text',
            description: 'Personal Token',
            id: 'token',
          },
        ],
      },
    ],
    sources: [],
    responsibleFor: {
      dataSynchronization: true,
    },
  });
});

Validate account

Since authentication is required we should run an authentication and return corresponding user name. You can find more information about the endpoint here.

app.post(`/validate`, (req, res) => {
  const user = users[req.body.fields.token];
  if (user) {
    return res.json({name: user.name});
  }

  res.status(401).json({message: `Unauthorized`});
});

Getting sync configuration

This is basic a scenario and we don’t need any dynamic. So we will return a static configuration with no filters.

app.post(`/api/v1/synchronizer/config`, (req, res) => {
  res.json({
    types: [
      {id: `flower`, name: `Flower`},
      {id: `regionPrice`, name: `Region Price`},
    ],
    filters: [],
  });
});

Getting schema

We should provide schema for selected types.

const schema = {
  flower: {
    id: {name: `Id`, type: `id`},
    name: {name: `Name`, type: `text`},
  },
  regionPrice: {
    id: {name: `Id`, type: `id`},
    name: {name: `Name`, type: `text`},
    price: {name: `Price`, type: `number`},
    flowerId: {
      name: `Flower Id`,
      type: `text`,
      relation: {
        cardinality: `many-to-one`,
        name: `Flower`,
        targetName: `Region Prices`,
        targetType: `flower`,
        targetFieldId: `id`,
      },
    },
  },
};

app.post(`/api/v1/synchronizer/schema`, (req, res) => {
  res.json(
    req.body.types.reduce((acc, type) => {
      acc[type] = schema[type];
      return acc;
    }, {}),
  );
});

Fetching data

The endpoint receives requested type, accounts, filter and set of selected types and should return actual data.

app.post(`/api/v1/synchronizer/data`, (req, res) => {
  const {requestedType, account} = req.body;

  return res.json({
    items: users[account.token].data[requestedType],
  });
});

And that’s it! Our app is ready for use. See full example here.

Getting started

General

HTTP API

AI & agents

Integrations

GraphQL API

Tutorial: Simple app

Getting app information

Validate account

Getting sync configuration

Getting schema

Fetching data

​Getting app information

​Validate account

​Getting sync configuration

​Getting schema

​Fetching data

Getting app information

Validate account

Getting sync configuration

Getting schema

Fetching data