Datasources: Fetching Data

Make your features more powerful using datasources to fetch data and render dynamic UI at runtime.

What Are Datasources?

A Datasource is any URL that provides data to a feature at runtime. In order to be used as a datasource, a URL must:

• be publicly accessible using javascript in the browser (have appropriate cross-origin headers)

• respond with a JSON payload

• respond to a GET request

Adding Datasources

Datasources are shared across all features in your project, and added using the Project panel under the Datasources tab. This reduces redundancy as multiple features that need to use the same data can share it, and allows events in one feature (say, a successful resource creation) to modify data used in another feature. Give it a name, provide a URL, any query or header parameters, and hit Fetch. You have now added a datasource to your Project.

The response is not stored by Mason, but used during the build process to determine the structure of the expected response and configure mapping rules for your data and UI. The response structure must be consistent.

Triggering Fetches

Datasources are created in your project, but fetched by your features when they mount. This is because you may not have all the dynamic data relevant to the datasource until a specific feature mounts. In order to tell a feature to fetch a datasource when it mounts, check the box next to the datasource name in the Configure section of the builder under the Fetch Datasources header. Ensure the feature that fetches the datasource has the appropriate url parameters and callbacks, if required.

Private Parameters

If you are using tokens or unique identifiers in your datasource, you may mark them as private using the key button in the Builder. Any header or query parameters marked as private will not be supplied to your Datasource at runtime, and must be provided by you using a callback (see below). All parameters not marked as private will be supplied to your features at runtime, and will be visible by anyone with access to your application.

Dynamic Parameters

You may inject dynamic header or query parameters, like authorization tokens, at runtime by using the willFetchData callback. Your function will receive the datasource to be fetched as an argument, which you may modify and return. See below for an example.

import React from 'react';
import { Canvas } from '@mason-api/react-sdk';

class MyFeed extends React.Component {
    render() {
        const { search, token, user } = this.props;
        return <Canvas 
            id="YOUR_COMPONENT_ID"
            willFetchData={(datasource, featureId) => {
                if (datasource.id === 'YOUR_DATASOURCE_ID') {
                    return {
                        ...datasource,
                        headers: { 'Authorization': token },
                        queries: { 'search': search },
                    };
                }
                return datasource;
            }}
        />;
    }
}

Your function will receive two arguments:

datasource, an object with the following structure

{
    url: 'https://example.test',
    headers: {
        'Content-Type': 'application/json'
    },
    queries: {
        foo: 'bar'
    },
    name: 'DATASOURCE_NAME',
    id: 'DATASOURCE_ID'

and featureId, the 12-byte unique identifier of your feature (which you can find in the Export instructions in the Builder).

You may modify any part of the datasource including the URL. However, URL modifications are most easily accomplished using the urlParams property. You must return the datasource, if you have no modifications return the datasource unmodified.

Registering Callbacks

As an alternative to providing callbacks using props, particularly if you are not using React, you may use the Mason.callback function to register your willSendData callback. Here is an example:

import Mason from '@mason-api/react-sdk';

Mason.callback('willSendData', (datasource, featureId) => {
    if (datasource.id === 'YOUR_DATASOURCE_ID') {
        return {
            ...datasource,
            headers: { 'Authorization': token },
            queries: { 'search': search },
        };
    }
    return datasource;
}, 'YOUR_FEATURE_ID');

The third argument to the callback function is an optional feature id. Even though datasources are shared across all features in a project, fetch events are triggered by feature's mounting (more on this below). If you want Mason to invoke a callback only when a specific feature is fetching a datasource, you may provide its id as the third argument.

Providing Data at Runtime

In some cases you may want to use a form submission response to update a datasource and trigger a UI update. To accomplish this, use the Success event menu in the Form tab of the Configure section of the Builder. You may merge or replace a datasource with the response from your form submission. You may also trigger a refetch of the entire datasource.

Replace simply overwrites the entire datasource. When merging, the behavior is as follows:

• if the Datasource is an object, the response will be shallowly merged

• if the Datasource is an array, and the response is not an array, the response will be pushed onto the end of the array

• if the Datasource is an array, and the response is an array, the response's entries will be pushed onto the end of the array