RESTApi

The RESTApi class provides a wrapper for consuming external REST APIs and converting responses to Arquero tables. Useful for integrating third-party data sources into Farseer workflows.

Creating an Instance

createInstance(baseURL, authObject)

Static factory method that creates an authenticated RESTApi instance.

static createInstance(
    baseURL: string,
    authObject: HeaderAuthentication | QueryParamsAuthentication | LogInAuthentication
): Promise<RESTApi>

Header Authentication

import { RESTApi } from 'farseer-client';

const api = await RESTApi.createInstance(
    'https://api.example.com',
    {
        headerKey: 'Authorization',
        headerValue: 'Bearer my-token'
    }
);

Query Parameter Authentication

const api = await RESTApi.createInstance(
    'https://api.example.com',
    {
        paramKey: 'api_key',
        paramValue: 'my-api-key'
    }
);

Login Authentication

const api = await RESTApi.createInstance(
    'https://api.example.com',
    {
        request: {
            url: '/auth/login',
            method: 'POST',
            data: { username: 'user', password: 'pass' }
        },
        headerParamToExtract: {
            keyToRead: 'token',
            keyToWrite: 'Authorization',
            valueInitial: 'Bearer ',
            target: 'headers'
        }
    }
);

---

Fetching Data

requestAndConvert(options)

Fetches data from the API and converts it to an Arquero table.

requestAndConvert(options: FetchDataAndConvertOptions): Promise<aq.internal.ColumnTable>

Options:

Parameter	Type	Required	Description
mainRequest	APIRequestConfig	Yes	Primary request configuration
responseTransform	string[] | Function	Yes	Path to extract data or transform function
preRequest	PreRequestConfig	No	Preliminary request (e.g., get CSRF token)
postRequest	APIRequestConfig	No	Post-request (e.g., logout)
paginationSettings	PaginationSettings	No	Pagination configuration

Basic Request

const data = await api.requestAndConvert({
    mainRequest: {
        url: '/api/products',
        method: 'GET'
    },
    responseTransform: ['data', 'items']  // Navigate: response.data.items
});

data.print();

With Transform Function

const data = await api.requestAndConvert({
    mainRequest: {
        url: '/api/sales',
        method: 'POST',
        data: { year: 2024, region: 'North' }
    },
    responseTransform: (response) => {
        return response?.data?.records?.map(r => ({
            product: r.product_name,
            amount: r.total_amount,
            date: r.sale_date
        }));
    }
});

With Pagination

const data = await api.requestAndConvert({
    mainRequest: {
        url: '/api/transactions',
        method: 'GET'
    },
    responseTransform: ['data'],
    paginationSettings: {
        paramHandlingType: 'query',
        limitParamName: 'limit',
        offsetParamName: 'offset',
        limitParamValue: 100
    }
});

With Pre-Request

const data = await api.requestAndConvert({
    mainRequest: {
        url: '/api/data',
        method: 'GET'
    },
    responseTransform: ['results'],
    preRequest: {
        requestConfig: {
            url: '/api/csrf-token',
            method: 'GET'
        },
        paramToExtract: {
            keyToRead: 'csrfToken',
            keyToWrite: 'X-CSRF-Token',
            target: 'headers'
        }
    }
});

---

Type Reference

APIRequestConfig

interface APIRequestConfig {
    url: string;
    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
    data?: Record<string, any>;
    headers?: Record<string, string>;
    queryParams?: Record<string, any>;
}

PaginationSettings

interface PaginationSettings {
    paramHandlingType: 'query' | 'headers';
    limitParamName: string;
    offsetParamName: string;
    limitParamValue: number;
}

HeaderAuthentication

interface HeaderAuthentication {
    headerKey: string;
    headerValue: string;
}

QueryParamsAuthentication

interface QueryParamsAuthentication {
    paramKey: string;
    paramValue: any;
}

LogInAuthentication

interface LogInAuthentication {
    request: APIRequestConfig;
    headerParamToExtract?: ParamToExtract;
}