Skip to main content

HTTP Client

Explanation

The @tramvai/module-http-client module adds functionality to the application related to API requests. Available providers allow you to create new services to work with any API and create more specific services with preset settings for specific APIs.

@tinkoff/request library is used under the hood, and provides a lot of important functionality:

Concepts

HTTP client

HTTP client - implementation of the HttpClient interface, created via the HTTP_CLIENT_FACTORY token. HTTP client accepts general settings, some of which will be used as defult values ​​for all requests. The HTTP client does not provide an opportunity to add additional methods for requests, and to perform side actions when the request is completed or failed.

Services for working with API

The API service inherits from the ApiService class, which is exported from @tramvai/http-client. The API service takes an HTTP client in its constructor and uses it for requests. The API service implements all methods for requests from the HttpClient interface, but allows you to modify them. For example, you can replace the implementation of the request method by adding an error message to the catch request via an HTTP client - this logic will automatically work for all other methods - get, put, post, delete. In the API service, you can add custom methods for requests to certain API endpoints, and specify only the necessary parameters in them, and type responses.

Additional reasons to create API services - if you need to use several different HTTP clients to work with a specific API, or you need the ability to add a convenient abstraction on top of the basic methods for sending requests.

Usage

Installation

You need to install @tramvai/module-http-client

yarn add @tramvai/module-http-client

And connect in the project

import { createApp } from '@tramvai/core';
import { HttpClientModule } from '@tramvai/module-http-client';

createApp({
name: 'tincoin',
modules: [HttpClientModule],
});

Create a new HTTP client

Each new HTTP client must directly or indirectly inherit HTTP_CLIENT_FACTORY.

caution

New HTTP clients / API services should not be created with scope: Scope.SINGLETON, because each request is supplemented with default parameters specific to each user, for example - passing the X-Real-Ip header from the request to the application in all requests to the API.

Basic HTTP client

The HTTP_CLIENT_FACTORY token - provides a factory for creating new HTTP clients. The options are preinstalled with a logger and a cache factory. HTTP_CLIENT_FACTORY default options will be applied to child HTTP clients.

Peculiarities
  • For all requests to the API, headers are added from the list returned by the API_CLIENT_PASS_HEADERS token, and X-Real-Ip from the current request to the application

Token interface:

type HTTP_CLIENT_FACTORY = (options: HttpClientFactoryOptions) => HttpClient;

Token use:

import { Scope, provide } from '@tramvai/core';
import { ENV_MANAGER_TOKEN } from '@tramvai/tokens-common';
import { HTTP_CLIENT_FACTORY } from '@tramvai/tokens-http-client';

const provider = provide({
provide: 'WHATEVER_API_HTTP_CLIENT',
useFactory: ({
factory,
envManager,
}: {
factory: typeof HTTP_CLIENT_FACTORY;
envManager: typeof ENV_MANAGER_TOKEN;
}) => {
return factory({
name: 'whatever-api',
baseUrl: envManager.get('WHATEVER_API'),
});
},
deps: {
factory: HTTP_CLIENT_FACTORY,
envManager: ENV_MANAGER_TOKEN,
},
});

Using existing HTTP clients

Most HTTP clients implement additional logic for requests, and inherit from ApiService. Thus, each service has methods get, post, put, delete and request, but there may be specific methods.

Common HTTP client

The HTTP_CLIENT token provides a basic client for sending requests to any URLs, Circuit Breaker is disabled.

Token use:

import { declareAction } from '@tramvai/core';
import { HTTP_CLIENT } from '@tramvai/tokens-http-client';

export const fetchAction = declareAction({
name: 'fetch',
async fn() {
const { payload, headers, status } = await this.deps.httpClient.get(
'https://www.domain.com/api/endpoint'
);
return payload;
},
deps: {
httpClient: HTTP_CLIENT,
},
});

Adding custom data to all requests

Let's consider a case using the abstract service WHATEVER_API_SERVICE as an example. Let's say we want to add an X-Real-Ip header to every request, interceptors allow this:

import { provide } from '@tramvai/core';
import { HttpClientRequest, HttpClient } from '@tramvai/http-client';
import { REQUEST_MANAGER_TOKEN } from '@tramvai/tokens-common';

const provider = provide({
provide: 'WHATEVER_API_SERVICE',
useFactory: ({
factory,
requestManager,
envManager,
}: {
factory: typeof HTTP_CLIENT_FACTORY;
requestManager: typeof REQUEST_MANAGER_TOKEN;
envManager: typeof ENV_MANAGER_TOKEN;
}) => {
return factory({
name: 'whatever-api',
baseUrl: envManager.get('WHATEVER_API'),
interceptors: [
(req, next) => {
return next({
...request,
headers: {
...request.headers,
'X-real-ip': requestManager.getClientIp(),
},
});
},
],
});
},
deps: {
factory: HTTP_CLIENT_FACTORY,
requestManager: REQUEST_MANAGER_TOKEN,
envManager: ENV_MANAGER_TOKEN,
},
});

Global configuration

All HTTP clients, created from HTTP_CLIENT_FACTORY, will have this factory default configuration. All of this options can be overridden when creating a new client, but sometimes it is very useful to set some global parameters for all clients, for example interceptors.

Interceptors

You can provide multi token DEFAULT_HTTP_CLIENT_INTERCEPTORS with interceptor, that will be applied to all HTTP clients:

import { DEFAULT_HTTP_CLIENT_INTERCEPTORS } from '@tramvai/tokens-http-client';

const provider = provide({
provide: DEFAULT_HTTP_CLIENT_INTERCEPTORS,
useValue: (req, next) => next(req),
});

Send files with FormData

You can send files with FormData by adding a few options to the request:

import { declareAction } from '@tramvai/core';

const action = declareAction({
name: 'my-action',
async fn(file: File) {
const data = await this.deps.myApi.post(
'/example/uploadFile',
{},
// add requestType: 'form' and put your files in the attaches array
// Note that there's no need to append files to the FormData, it will be done internally
{ requestType: 'form', attaches: [file] }
);

return data.payload;
},
deps: {
myApi: 'WHATEVER_API_SERVICE'
},
});

How to

How to disable HTTP request caching?

To disable caching for all HTTP clients, pass the env variable HTTP_CLIENT_CACHE_DISABLED: true to the application

How to modify request?

Interceptor example:

const interceptor = (req, next) => next({
...req,
headers: {
...req.headers,
'X-custom-header': 'intercepted',
},
});

How to modify response?

Interceptor example:

const interceptor = (req, next) => {
return next(req)
.then((res) => ({
...res,
payload: `${res.payload}-intercepted`,
}));
};

How to mock response?

Interceptor example:

const interceptor = (req, next) => {
return Promise.resolve({
status: 200,
headers: {},
payload: 'mocked',
});
};

How catch all request stages?

Interceptor example:

const interceptor = (req, next) => {
console.log('start');

return next(req)
.then((res) => {
console.log('success');
return res;
})
.catch((reason) => {
console.log('failure');
throw reason;
});
};

How to use any HTTP Client in interceptor?

For prevent cycle dependencies, you need to resolve HTTP Client from DI in runtime:

const provider = provide({
provide: DEFAULT_HTTP_CLIENT_INTERCEPTORS,
useFactory: ({ di }): ExtractTokenType<typeof DEFAULT_HTTP_CLIENT_INTERCEPTORS> => {
return (req, next) => {
const httpClient = di.get(HTTP_CLIENT);
return next(req);
};
},
deps: {
di: DI_TOKEN,
},
});

Testing

Testing your api clients

If you have a module or providers that define api-clients, then it will be convenient to use special utilities in order to test them separately

import { testApi } from '@tramvai/module-http-client/tests';
import { CustomModule } from './module';

describe('testApi', () => {
it('test', async () => {
const { di, fetchMock, mockJsonResponse } = testApi({
modules: [CustomModule],
env: {
TEST_API: 'testApi',
},
});
const httpClient: typeof HTTP_CLIENT = di.get('CUSTOM_HTTP_CLIENT') as any;

mockJsonResponse({ a: 'aaa' });

const { payload } = await httpClient.get('test');

expect(payload).toEqual({ a: 'aaa' });
expect(fetchMock).toHaveBeenCalledWith('http://testApi/test', expect.anything());
});
});

Logging

By default, @tinkoff/request will log every failed requests with level error. You can disable logging by pass { silent: true } parameter to request parameters. Useful meta information about request will be available in error.__meta property.

Example:

const log = logger('request:test');

httpClient.request({ path: 'test', silent: true }).catch((error) => {
log.info(error);
});

Debug

You can show all the default logs of http clients by providing these env variables:

LOG_ENABLE=request*
LOG_LEVEL=trace

If the built-in http clients logs are not enough, you can enable NodeJS debugging of the request module this way:

NODE_DEBUG=request tramvai start <appName>

Environment Variables

API Reference

You can find HttpClient and ApiService interfaces in @tramvai/http-client package documentation

HttpClient

type HttpClient = {
// common method for sending HTTP requests
request<P = any>(request: HttpClientRequest): Promise<HttpClientResponse<P>>;
// method for sending GET requests
get<R = any>(
path: string,
payload?: Pick<HttpClientRequest, 'query' | 'headers'>,
config?: Omit<HttpClientRequest, 'url' | 'query' | 'body' | 'headers'>
): Promise<HttpClientResponse<R>>;
// method for sending POST requests, uses `requestType: 'json'` by default
post<R = any>(
path: string,
payload?: Pick<HttpClientRequest, 'query' | 'body' | 'headers'>,
config?: Omit<HttpClientRequest, 'url' | 'query' | 'body' | 'headers'>
): Promise<HttpClientResponse<R>>;
// method for sending PUT requests, uses `requestType: 'json'` by default
put<R = any>(
path: string,
payload?: Pick<HttpClientRequest, 'query' | 'body' | 'headers'>,
config?: Omit<HttpClientRequest, 'url' | 'query' | 'body' | 'headers'>
): Promise<HttpClientResponse<R>>;
// method for sending DELETE requests
delete<R = any>(
path: string,
payload?: Pick<HttpClientRequest, 'query' | 'headers'>,
config?: Omit<HttpClientRequest, 'url' | 'query' | 'body' | 'headers'>
): Promise<HttpClientResponse<R>>;
// method for creating a new instance of the HTTP client, based on the settings of the current
fork(options?: HttpClientRequest, mergeOptionsConfig?: { replace?: boolean }): HttpClient;
};

HttpClientRequest

type HttpClientRequest = {
// absolute url of the request, do not use simultaneously with `path`
url?: string;
// url of the request, not to be used simultaneously with `url`
path?: string;
// base url, which is added to all queries before the `path` value
baseUrl?: string;
// basic HTTP methods are supported - GET, POST, PUT, DELETE
method?: HttpMethod;
// request data type, `form` by default
requestType?: HttpContentType;
// response data type, is calculated from the `content-type` header by default
responseType?: HttpContentType;
// HTTP request headers
headers?: Record<string, any>;
// request query parameters
query?: Record<string, any>;
// request body
body?: Record<string, any>;
// request execution time limit, in ms
timeout?: number;
// disabling logging inside the HTTP client. It is recommended to use if a request error is logged manually
silent?: boolean;
// disabling the request cache
cache?: boolean;
// if `abortPromise` is resolved, the request will be canceled
abortPromise?: Promise<void>;
// AbortController signal, will be passed to fetch
signal?: AbortSignal;
// request credentials mode, default is `same-origin`, will be passed to fetch
credentials?: RequestCredentials;
// will intercept all requests
interceptors?: HttpClientInterceptor[];
// method to modify request data
// @deprecated - use interceptors instead
modifyRequest?: (req: HttpClientRequest) => HttpClientRequest;
// method to modify response data
// @deprecated - use interceptors instead
modifyResponse?: <P = any>(res: HttpClientResponse<P>) => HttpClientResponse<P>;
// method to modify the error object
// @deprecated - use interceptors instead
modifyError?: (error: HttpClientError, req: HttpClientRequest) => HttpClientError;
[key: string]: any;
};

HttpClientResponse

type HttpClientResponse<P = any> = {
// response body
payload: P;
// HTTP response code
status: number;
// HTTP response headers
headers: Record<string, any>;
};

HttpClientError

type HttpClientError = Error & {
// HTTP response code, only exists when request was finished
status?: number;
// HTTP response headers, only exists when request was finished
headers?: Record<string, any>;
[key: string]: any;
};

HttpClientInterceptor

type HttpClientInterceptor = (
request: HttpClientRequest,
next: (request: HttpClientRequest) => Promise<HttpClientResponse>
) => Promise<HttpClientResponse>;

ApiService

ApiService - abstract class for easy creation of services for working with API, allows you to override custom logic in the request method, on top of which the rest of the basic methods work.

For example, a service that automatically displays a pop-up window when a request error occurs:

class CustomApiService extends ApiService {
constructor({ httpClient }: { httpClient: HttpClient }) {
super(httpClient);
}

request<R = any>(request: HttpClientRequest): Promise<HttpClientResponse<R>> {
return this.httpClient.request(request).catch((error) => {
alert(error);
});
}
}

const service = new CustomApiService({ httpClient });

service.request({ path: 'fake' }); // show alert
service.get('fake'); // also show alert