docs/gitbook
GitHub

Getting Started

HTTP

A simple HTTP client for web apps. Supports interceptors & global configuration.

Quick start

Installation:

npm install @coolio/http

Initialize a HttpClient and configure it as below:

import { bodyParser, bodySerializer, BodyCasing, ContentType, HttpClient, fetchRequestHandler } from '@coolio/http';
import { Config } from './config';

export const httpClient = new HttpClient({
  baseUrl: 'https://api.headline1.com/v1/',
  requestHandler: fetchRequestHandler,
  defaultHeadersProvider: (host: string) => ({
    'Content-Type': ContentType.JSON,
    'Authorization': host === Config.API_DOMAIN ? 'Bearer abcdef1234567890' : undefined,
  }),
  bodyParser: bodyParser({ 
    bodyCasing: BodyCasing.CAMEL_CASE
  }),
  bodySerializer: bodySerializer({
    bodyCasing: BodyCasing.SNAKE_CASE
  }),
});

Use the client in repositories containing API bindings:

import { httpClient } from './httpClient';
import { Config } from './config';
import { User } from './user.types';

const getUsers = async (): Promise<User[]> => {
  const response = await httpClient.get(`${Config.API_BASE_URL}/users`, {
    query: {
      page: 3,
      limit: 10,
    },
  });
  const body = await response.parsedBody();
  return body.data;
};

const getProfile = async (): Promise<User> => {
  const response = await httpClient.get(`${Config.API_BASE_URL}/me`);
  return await response.parsedBody();
};

export const UserRepository = {
  getUsers,
  getProfile,
};

After doing the following, you can simply call UserRepository.getProfile() to receive the Promise returning User object.

HttpClient Options

Interceptors

Quite often we need to do something "in-between" while our API requests are running. This is why we have a built-in interceptors mechanism. They can:

  • throw errors if response status code indicates that request failed,

  • automagically retry request up to X times if it failed,

  • transparently reauthorize if your access token has been revoked

The first case is described below:

import { HttpFetch, HttpCode, ResponseError, NormalizedHttpOptions } from '@coolio/http';

export const errorInterceptor = <Body>(
  request: HttpFetch<Body>,
  options: NormalizedHttpOptions,
): HttpFetch<Body> => {
  return () => request().then(response => {
    // You can always use `HttpCode` enum as in this case, however
    // `response.status < 400` would be better in this case
    if(response.status === HttpCode.OK){
      return response;
    }
    throw new ResponseError(response);
  })
};

// In your httpClient.ts add the following:

httpClient.addInterceptor(errorInterceptor);

As you can see, interceptors accept two arguments:

  • HttpFetch - a function that returns a Promise that performs http request. It allows to queue or delay multiple requests, retry them etc.

  • NormalizedHttpOptions - options that can be modified before request is made, i.e. you can add Authorization header in your authInterceptor.

Advanced Use Cases

If you happen to use JSON API, you may benefit from using a wrapper library that handles most of it's specs:

npm install @coolio/json-api
# or if you're using fancy stuff:
yarn add @coolio/json-api

See @coolio/json-api's README.md for details.

PreviousChangelogNextInterceptors

Last updated