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

Hosts

A RESTApi sends requests only to the host of its base URL, and only over https when the base URL uses https, so its credentials can't reach another host through an absolute URL or a redirect. A request or redirect to another host, or from https to plain http, is refused with an error. To call another host, create a separate RESTApi for it. The login request is the exception: it may go to another host, such as an OAuth2 token endpoint, and its redirects stay on that host.

---

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;
}