1.5.10 • Public • Published



Base API client backed by axios.

Version Bundle size Downloads

CodeFactor SonarCloud Codacy Scrutinizer

Dependencies Security Build Status Coverage Status

Commit activity FOSSA License Made in Ukraine

🇺🇦 Help Ukraine

I woke up on my 26th birthday at 5 am from the blows of russian missiles. They attacked the city of Kyiv, where I live, as well as the cities in which my family and friends live. Now my country is a war zone.

We fight for democratic values, freedom, for our future! Once again Ukrainians have to stand against evil, terror, against genocide. The outcome of this war will determine what path human history is taking from now on.

💛💙 Help Ukraine! We need your support! There are dozen ways to help us, just do it!

Table of Contents


Platform Status

To use library you need to have node and npm installed in your machine:

  • node >=10
  • npm >=6

Package is continuously tested on darwin, linux and win32 platforms. All active and maintenance LTS node releases are supported.


To install the library run the following command

  npm i --save base-api-client


Example of telegram client extended from BaseAPI:

import BaseAPI from 'base-api-client';

export default class TelegramAPI extends BaseAPI {
    constructor(id, token) {

    message(chatId, html) {
        return'sendMessage', {
            'parse_mode' : 'HTML',
            'text'       : html,
            'chat_id'    : chatId

    file(chatId, fileId) {
        return'sendDocument', {
            'document' : fileId,
            'chat_id'  : chatId

Constructor arguments

  1. url - base URL of the API. Can consist apiPrefix. Will be cast to nodeJS URL object.
  2. options - object with next attributes:
    • timeout - timeout in ms format. Will be cast to integer (in milliseconds). Default: 1m.
    • logger - if applied, will add debug and verbose messages before and after each request. Should have next interface: logger.log(level, object).


HTTP methods:

  • get(url, params, options)
  • post(url, data, options)
  • patch(url, data, options)
  • put(url, data, options)
  • delete(url, options)

in all aforementioned methods url can be both global, or relative to base URL (defined in constructor). params are url query params, and data is JSON body. options are passed directly to axios request


Implement getHeaders() method to define select headers for API. Alternativelly, pass headers in options for each request if headers need behave differently.

Basic auth use auth setting, if you want to use basic auth for each request.

this.auth = {
    username : '',
    password : ''

Data processing

Next methods can be used for default data pre/post-processing:

        onError(error) {
            if (error.isAxiosError) {
                throw new API_ERROR(error);
            throw error;

        onResponse(res) {


the package exposes API_ERROR, that can be used outside:

import BaseAPI, { API_ERROR } from 'base-api-client';

class API extends BaseAPI {
    constructor() {

    async createUser(email) {
        try {
            const user = await'/users', { email });

        } catch (error) {
            if (error instanceof API_ERROR) {
                console.log('raw http error:', error.payload);
                throw error;

Logging and Tracing

You can pass logger while api creation, but also this can be done by calling initLogger(logger) method directly.

Alternatively, use polymorphism and implement the log(level, data) method on descendants.

Autogenerated Trace ID is atached to each log. If you need control over traceId generation, implement getTraceId(reqOptions, settings) method.


Depending on selected approach use setMock(mockFuction) or implement _axios(axiosOptions) method. Both mockFuction and _axios will receive axios options instead of axios instance, and should return expected result. Default mock function is () => ({ data: 1 }).

To check examples of api mocks and tesing, see implementation section.


Looking for more examples? Check real implementations of famous APIs:

API Organization Reference Examples
Telegram Bot Telegram Bot API Telegram Telegraph API
AWS SNS Amazon AWS docs
Gitea Gitea Swagger
GitHub Apps Microsoft Apps Reference
GitHub Repos Microsoft Repositories Reference
Heroku Salesforce Platform API Reference
Confluence Atlassian REST API


Make the changes to the code and tests. Then commit to your branch. Be sure to follow the commit message conventions. Read Contributing Guidelines for details.




DownloadsWeekly Downloads






Unpacked Size

62.4 kB

Total Files


Last publish


  • pustovit