Fetch API Call

Awesome fetch api for browser and nodejs with interceptors easy way to declare api endpoints. Provide very easy way to setup api for different backends/services.

# Advantages

• Support interceptors
• Support multiple instances wiht its own interceptors
• Easy way to define headers for specific requests
• Declrative api end points

const login = api('POST /login');
login({});

const loadStatistics = api('GET /statistics');
loadStatistics({
  filter: {},
});

const loadUser = api('GET /user/:id');
laodUser({
  id: 1,
});

# Install

yarn add fetch-api-call

# Api Declaration

import fetchApiCall from 'fetch-api-call';

const { api } = fetchApiCall({
  protocol: process.env.API_PROTOCOL,
  host: process.env.API_HOST,
});

Options:

• protocol - http protocol. Available values - http: an https:
• host - server hostname
• headers - requests headers. NOTE that headers could be also set with interceptors
• mode - more details at - https://developer.mozilla.org/en-US/docs/Web/API/Request/mode
• prefix - api url prefix. Useful when there are multiple api versions:
  • /user
  • /v1/user
  • /v2/user

api - function to define api methods in single line of code.

const apiCall = api('HTTP_METHOD /api/path/:with/:placeholders');

apiCall(params = {}, headers = {}) - function takes two optional params:

• params - api params. Also is used for building final api entrypoint. More detauls see at Api Url Definition and Placeholders.
• headers - certain request headers.

Examples:

// user login api
const login = api('POST /login');
login({
  username,
  password,
});

// user logout api
const logout = api('POST /logout');
logout();

// get user api
const getUser = api('GET /user/:id');
getUser({
  id: 1,
});

# Interceptors

import fetchApiCall from 'fetch-api-call';

const { api, interceptors } = fetchApiCall({
  protocol: process.env.API_PROTOCOL,
  host: process.env.API_HOST,
});

interceptors methods:

• addRequestInterceptor(request)
• addResponseInterceptor(response)
• addErrorInterceptor(error)

Each methods return function to remove interceptor.

Iterceptors will be called for all request done with api.

// user login api
const login = api('POST /login');
let removeAcessTokenIterceptor = null;

login({}).then(({ acessToken }) => {
  removeAcessTokenIterceptor = iterceptors.addRequestInterceptor(request => {
    request.headers.set('Acess-Token', acessToken);
    return request;
  });
});

// user logout api
const logout = api('POST /logout');
logout().then(() => {
  removeAcessTokenIterceptor();
});

// get user api
const getUser = api('GET /user/:id');
getUser({
  id: 1,
});

# Request Headers

This is useful when using fetch-api-call on NodeJS. In some cases it is not possible to use interceptors to set auth headers becasue it will work for all request. We should specify certain request with certain header.

const getStatistics = api('GET /statistics');
getStatistics(
  {},
  {
    headers: {
      MyCustomHeader: '123zxc',
    },
  }
);

# Multiple Api Instances

Very useful if there is microservices backend architecture.

import fetchApiCall from 'fetch-api-call';

const Auth = fetchApiCall({
  host: process.env.AUTH_API_HOST,
});

const Users = fetchApiCall({
  host: process.env.USERS_API_HOST,
});

const Data = fetchApiCall({
  host: process.env.DATA_API_HOST,
  prefix: 'v2',
});

const login = Auth.api('POST /login').then(({ accessToken }) => {
  Users.interceptors.addRequest(res => {
    request.headers.set('Acess-Token', acessToken);
    return request;
  });

  Data.interceptors.addRequest(res => {
    request.headers.set('Acess-Token', acessToken);
    return request;
  });
});

const loadStatisitcs = Data.api('GET /statisitcs');
loadStatisitcs({
  filter: {
    //...
  },
});

# Custom Setup

import setup from 'fetch-api-call/setup';
import fetchAdapter from 'bivrost-fetch-adapter';

const createApi = setup({
  headers: {
    'Content-Type': 'application/json',
  },
  mode: 'cors',
  adapter: fetchAdapter,
  interceptors: {
    resposne: res => res,
    request: req => req,
    error: err => err,
  },
});

const api = createApi({
  protocol: process.env.API_PROTOCOL,
  host: process.env.API_HOST,
});

const login = api('POST /login');

Options:

• headers - default headers
• mode - default mode. More details at - https://developer.mozilla.org/en-US/docs/Web/API/Request/mode
• adapter - default HTTP adapter. See more at - https://tuchk4.github.io/bivrost/docs/adapters.html
• interceptors - initial interceptors. NOTE that this is NOT DEFAULT interceptors.