Skip to main content

API Reference

Complete API reference for the HTTP client plugin.

HTTPClient​

Main HTTP client class.

Constructor​

new HTTPClient(config?: HTTPClientConfig, options?: HTTPClientOptions)

HTTP Methods​

get()​

get<T>(url: string, config?: RequestConfig): Promise<HTTPResponse<T>>

Make a GET request.

Example:

const response = await client.get<User>('/users/123');
console.log(response.data);

post()​

post<T>(url: string, data?: unknown, config?: RequestConfig): Promise<HTTPResponse<T>>

Make a POST request.

Example:

const response = await client.post<User>('/users', {
  name: 'John Doe',
  email: 'john@example.com'
});

put()​

put<T>(url: string, data?: unknown, config?: RequestConfig): Promise<HTTPResponse<T>>

Make a PUT request.

patch()​

patch<T>(url: string, data?: unknown, config?: RequestConfig): Promise<HTTPResponse<T>>

Make a PATCH request.

delete()​

delete<T>(url: string, config?: RequestConfig): Promise<HTTPResponse<T>>

Make a DELETE request.

head<T>(url: string, config?: RequestConfig): Promise<HTTPResponse<T>>

Make a HEAD request.

options()​

options<T>(url: string, config?: RequestConfig): Promise<HTTPResponse<T>>

Make an OPTIONS request.

request()​

request<T>(config: RequestConfig): Promise<HTTPResponse<T>>

Make a generic HTTP request.

Example:

const response = await client.request<User>({
  method: 'GET',
  url: '/users/123',
  headers: {
    'X-Custom-Header': 'value'
  }
});

Interceptor Methods​

addRequestInterceptor()​

addRequestInterceptor(interceptor: RequestInterceptor): number

Add a request interceptor. Returns interceptor ID.

Example:

const id = client.addRequestInterceptor({
  onFulfilled: (config) => {
    config.headers['X-Timestamp'] = Date.now().toString();
    return config;
  }
});

addResponseInterceptor()​

addResponseInterceptor(interceptor: ResponseInterceptor): number

Add a response interceptor. Returns interceptor ID.

Example:

const id = client.addResponseInterceptor({
  onFulfilled: (response) => {
    console.log('Response received:', response.status);
    return response;
  }
});

removeInterceptor()​

removeInterceptor(id: number, type: 'request' | 'response'): void

Remove an interceptor by ID.

Example:

client.removeInterceptor(id, 'request');

Circuit Breaker Methods​

getCircuitState()​

getCircuitState(): string

Get current circuit breaker state: 'CLOSED', 'OPEN', or 'HALF_OPEN'.

resetCircuitBreaker()​

resetCircuitBreaker(): void

Manually reset the circuit breaker to CLOSED state.

Utility Methods​

getAxiosInstance()​

getAxiosInstance(): AxiosInstance

Get the underlying Axios instance for advanced usage.

Types​

HTTPClientConfig​

interface HTTPClientConfig {
  baseURL?: string;
  timeout?: number;
  headers?: Record<string, string>;
  auth?: AuthConfig;
  maxRedirects?: number;
  validateStatus?: (status: number) => boolean;
  decompress?: boolean;
  proxy?: ProxyConfig;
}

HTTPClientOptions​

interface HTTPClientOptions {
  retry?: RetryConfig;
  circuitBreaker?: CircuitBreakerConfig;
  logging?: boolean;
  timing?: boolean;
  requestInterceptors?: RequestInterceptor[];
  responseInterceptors?: ResponseInterceptor[];
}

RetryConfig​

interface RetryConfig {
  enabled: boolean;
  maxRetries?: number;
  retryDelay?: number;
  backoff?: 'linear' | 'exponential';
  retryCondition?: (error: HTTPClientError) => boolean;
  retryStatusCodes?: number[];
}

CircuitBreakerConfig​

interface CircuitBreakerConfig {
  enabled: boolean;
  threshold?: number;
  timeout?: number;
  resetTimeout?: number;
}

AuthConfig​

interface AuthConfig {
  type: 'basic' | 'bearer' | 'custom';
  username?: string;
  password?: string;
  token?: string;
  customHeader?: string;
}

HTTPResponse​

interface HTTPResponse<T = unknown> {
  data: T;
  status: number;
  statusText: string;
  headers: Record<string, string>;
  config: RequestConfig;
  duration?: number;
}

RequestConfig​

interface RequestConfig extends AxiosRequestConfig {
  retry?: Partial<RetryConfig>;
  metadata?: Record<string, unknown>;
}

Error Classes​

HTTPClientErrorImpl​

Base error class for all HTTP client errors.

class HTTPClientErrorImpl extends Error {
  code?: string;
  statusCode?: number;
  config?: RequestConfig;
  response?: {
    data: unknown;
    status: number;
    headers: Record<string, string>;
  };
  isNetworkError: boolean;
  isTimeout: boolean;
  originalError?: unknown;
}

HTTPResponseError​

HTTP response errors (4xx, 5xx).

class HTTPResponseError extends HTTPClientErrorImpl {
  isClientError(): boolean;
  isServerError(): boolean;
  
  static badRequest(message: string, data?: unknown): HTTPResponseError;
  static unauthorized(message?: string, data?: unknown): HTTPResponseError;
  static forbidden(message?: string, data?: unknown): HTTPResponseError;
  static notFound(message?: string, data?: unknown): HTTPResponseError;
  static conflict(message: string, data?: unknown): HTTPResponseError;
  static unprocessableEntity(message: string, data?: unknown): HTTPResponseError;
  static tooManyRequests(message?: string, data?: unknown): HTTPResponseError;
  static internalServerError(message?: string, data?: unknown): HTTPResponseError;
  static badGateway(message?: string, data?: unknown): HTTPResponseError;
  static serviceUnavailable(message?: string, data?: unknown): HTTPResponseError;
  static gatewayTimeout(message?: string, data?: unknown): HTTPResponseError;
}

HTTPTimeoutError​

Request timeout errors.

class HTTPTimeoutError extends HTTPClientErrorImpl {}

HTTPNetworkError​

Network errors.

class HTTPNetworkError extends HTTPClientErrorImpl {}

HTTPCircuitBreakerError​

Circuit breaker open errors.

class HTTPCircuitBreakerError extends HTTPClientErrorImpl {}

Type Guards​

isHTTPClientError()​

function isHTTPClientError(error: unknown): error is HTTPClientError

Check if error is an HTTP client error.

isHTTPResponseError()​

function isHTTPResponseError(error: unknown): error is HTTPResponseError

Check if error is an HTTP response error.

isHTTPTimeoutError()​

function isHTTPTimeoutError(error: unknown): error is HTTPTimeoutError

Check if error is a timeout error.

isHTTPNetworkError()​

function isHTTPNetworkError(error: unknown): error is HTTPNetworkError

Check if error is a network error.

Interceptor Factories​

createLoggingInterceptor()​

function createLoggingInterceptor(
  logger?: Logger
): { request: RequestInterceptor; response: ResponseInterceptor }

Create logging interceptors.

createTimingInterceptor()​

function createTimingInterceptor(): 
  { request: RequestInterceptor; response: ResponseInterceptor }

Create timing interceptors.

createCorrelationIdInterceptor()​

function createCorrelationIdInterceptor(
  headerName?: string,
  generator?: () => string
): RequestInterceptor

Create correlation ID interceptor.

createAuthInterceptor()​

function createAuthInterceptor(
  getToken: () => string | Promise<string>,
  headerName?: string,
  prefix?: string
): RequestInterceptor

Create authentication interceptor.

createRetryInterceptor()​

function createRetryInterceptor(
  retryConfig: RetryConfig
): ResponseInterceptor

Create retry interceptor.

createErrorNormalizationInterceptor()​

function createErrorNormalizationInterceptor(): ResponseInterceptor

Create error normalization interceptor.

Plugin​

AxiosHTTPClientPlugin​

class AxiosHTTPClientPlugin implements Plugin {
  readonly metadata: PluginMetadata;
  
  initialize(context: PluginContext): Promise<void>;
  start(): Promise<void>;
  stop(): Promise<void>;
  healthCheck(): Promise<HealthCheckResult>;
  
  getClient(name?: string): HTTPClient | undefined;
  getClientNames(): string[];
}

Next Steps​