Axios Client

The Axios client wraps the popular Axios library, providing advanced features like request/response interceptors, automatic JSON transformation, and request cancellation.

Installation

npm install @hey-api/client-axios axios

Axios is a peer dependency and must be installed separately.

Basic Usage

Create a client instance

import { createClient } from '@hey-api/client-axios';

const client = createClient({
  baseURL: 'https://api.example.com',
});

Make API calls

// GET request
const response = await client.get({
  url: '/users/{id}',
  path: { id: 123 },
});

if (response.error) {
  console.error('Error:', response.error);
} else {
  console.log('User:', response.data);
}

Configuration

The Axios client extends Axios configuration with OpenAPI TypeScript features:

Client Options

import { createClient } from '@hey-api/client-axios';
import axios from 'axios';

const client = createClient({
  // Base URL for all requests
  baseURL: 'https://api.example.com',

  // Axios instance (optional)
  axios: axios.create({
    timeout: 5000,
  }),

  // Default headers
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your-api-key',
  },

  // Error handling
  throwOnError: false,

  // Authentication
  auth: async (auth) => getToken(),

  // Body serialization
  bodySerializer: (body) => JSON.stringify(body),

  // Query serialization (Axios native)
  paramsSerializer: (params) => {
    return new URLSearchParams(params).toString();
  },

  // Custom query serialization (OpenAPI TypeScript)
  querySerializer: {
    array: { style: 'form', explode: true },
    object: { style: 'deepObject', explode: true },
  },

  // Request validator
  requestValidator: async (data) => validateRequest(data),

  // Response transformer
  responseTransformer: async (data) => transformResponse(data),

  // Response validator
  responseValidator: async (data) => validateResponse(data),

  // Standard Axios options
  timeout: 10000,
  maxRedirects: 5,
  maxContentLength: 2000,
  maxBodyLength: 2000,
  responseType: 'json', // 'json' | 'text' | 'stream' | 'blob' | 'arraybuffer'
  responseEncoding: 'utf8',
  validateStatus: (status) => status >= 200 && status < 300,
  withCredentials: false,
});

Custom Axios Instance

Use an existing Axios instance:

import { createClient } from '@hey-api/client-axios';
import axios from 'axios';

// Create custom Axios instance
const axiosInstance = axios.create({
  timeout: 5000,
  headers: {
    'X-Custom-Header': 'value',
  },
});

// Add Axios interceptors
axiosInstance.interceptors.request.use((config) => {
  console.log('Request:', config.url);
  return config;
});

// Use with OpenAPI TypeScript client
const client = createClient({
  baseURL: 'https://api.example.com',
  axios: axiosInstance,
});

Access Axios Instance

const client = createClient({
  baseURL: 'https://api.example.com',
});

// Access the underlying Axios instance
client.instance.defaults.timeout = 5000;

// Add Axios interceptors
client.instance.interceptors.request.use((config) => {
  console.log('Request:', config.url);
  return config;
});

HTTP Methods

GET
POST
PUT
PATCH
DELETE

const response = await client.get({
  url: '/users',
  query: {
    page: 1,
    limit: 10,
  },
});

if (!response.error) {
  console.log('Users:', response.data);
  console.log('Status:', response.status);
  console.log('Headers:', response.headers);
}

const response = await client.post({
  url: '/users',
  body: {
    name: 'John Doe',
    email: '[email protected]',
  },
});

if (!response.error) {
  console.log('Created user:', response.data);
}

const response = await client.put({
  url: '/users/{id}',
  path: { id: 123 },
  body: {
    name: 'Jane Doe',
  },
});

const response = await client.patch({
  url: '/users/{id}',
  path: { id: 123 },
  body: {
    email: '[email protected]',
  },
});

const response = await client.delete({
  url: '/users/{id}',
  path: { id: 123 },
});

if (!response.error) {
  console.log('User deleted');
}

Response Format

The Axios client returns Axios response objects:

const response = await client.get({ url: '/users' });

// On success
if (!response.error) {
  response.data;       // Response data
  response.status;     // HTTP status code
  response.statusText; // HTTP status message
  response.headers;    // Response headers
  response.config;     // Request configuration
}

// On error
if (response.error) {
  response.error;      // Error data from response
  response.status;     // HTTP status code
  response.statusText; // HTTP status message
  response.response;   // Full error response
  response.config;     // Request configuration
}

Authentication

Bearer Token

const client = createClient({
  baseURL: 'https://api.example.com',
  auth: async (auth) => {
    if (auth.scheme === 'bearer') {
      const token = await getAccessToken();
      return token;
    }
  },
});

Basic Authentication

const client = createClient({
  baseURL: 'https://api.example.com',
  auth: async (auth) => {
    if (auth.scheme === 'basic') {
      // Return base64 encoded credentials
      return btoa('username:password');
    }
  },
});

API Key

const client = createClient({
  baseURL: 'https://api.example.com',
  auth: async (auth) => {
    if (auth.type === 'apiKey') {
      return process.env.API_KEY;
    }
  },
});

// Per-request security
const response = await client.get({
  url: '/protected',
  security: [
    {
      type: 'apiKey',
      in: 'header',
      name: 'X-API-Key',
    },
  ],
});

Server-Sent Events

Stream real-time data with Server-Sent Events:

const stream = await client.sse.get({
  url: '/events',
  onSseEvent: (event) => {
    console.log('Event:', event.data);
  },
  onSseError: (error) => {
    console.error('Stream error:', error);
  },
  sseMaxRetryAttempts: 3,
  sseMaxRetryDelay: 5000,
});

// Close the stream
stream.close();

Request Cancellation

Cancel requests using Axios CancelToken or AbortController:

AbortController (Recommended)

const controller = new AbortController();

const promise = client.get({
  url: '/users',
  signal: controller.signal,
});

// Cancel the request
controller.abort();

Axios CancelToken

import axios from 'axios';

const source = axios.CancelToken.source();

const promise = client.get({
  url: '/users',
  cancelToken: source.token,
});

// Cancel the request
source.cancel('Request cancelled by user');

Advanced Features

Progress Monitoring

const response = await client.post({
  url: '/upload',
  body: formData,
  onUploadProgress: (progressEvent) => {
    const percentCompleted = Math.round(
      (progressEvent.loaded * 100) / progressEvent.total
    );
    console.log('Upload progress:', percentCompleted + '%');
  },
  onDownloadProgress: (progressEvent) => {
    console.log('Download progress:', progressEvent.loaded);
  },
});

Response Type

// Download file as blob
const response = await client.get({
  url: '/file.pdf',
  responseType: 'blob',
});

if (!response.error) {
  const blob = response.data;
  const url = URL.createObjectURL(blob);
  window.open(url);
}

// Stream response
const response = await client.get({
  url: '/large-file',
  responseType: 'stream',
});

if (!response.error) {
  response.data.on('data', (chunk) => {
    console.log('Chunk:', chunk);
  });
}

Request Retry

Use axios-retry for automatic retries:

import { createClient } from '@hey-api/client-axios';
import axios from 'axios';
import axiosRetry from 'axios-retry';

const axiosInstance = axios.create();

axiosRetry(axiosInstance, {
  retries: 3,
  retryDelay: axiosRetry.exponentialDelay,
  retryCondition: (error) => {
    return axiosRetry.isNetworkOrIdempotentRequestError(error)
      || error.response?.status === 429;
  },
});

const client = createClient({
  baseURL: 'https://api.example.com',
  axios: axiosInstance,
});

Proxy Configuration

const client = createClient({
  baseURL: 'https://api.example.com',
  proxy: {
    host: 'proxy.example.com',
    port: 8080,
    auth: {
      username: 'user',
      password: 'pass',
    },
  },
});

HTTP/HTTPS Agents

import https from 'https';

const client = createClient({
  baseURL: 'https://api.example.com',
  httpsAgent: new https.Agent({
    rejectUnauthorized: false,
    keepAlive: true,
  }),
});

TypeScript Types

import type {
  Client,
  Config,
  RequestOptions,
  RequestResult,
} from '@hey-api/client-axios';
import type { AxiosInstance, AxiosResponse } from 'axios';

// Custom client wrapper
function createApiClient(config: Config): Client {
  const client = createClient(config);
  
  // Access Axios instance
  const instance: AxiosInstance = client.instance;
  
  return client;
}

// Type-safe response
type UserResponse = RequestResult<
  { id: number; name: string },
  { message: string }
>;

const response: UserResponse = await client.get({
  url: '/users/1',
});

Comparison with Fetch Client

Feature	Axios Client	Fetch Client
Dependencies	Requires Axios	Zero dependencies
Browser Support	IE11+	Modern browsers
Node.js Support	Built-in	Requires polyfill
Request Cancellation	CancelToken, AbortController	AbortController
Progress Events	Yes	No
Interceptors	Axios + OpenAPI	OpenAPI only
Response Type	Automatic JSON	Manual parsing
Bundle Size	~13KB	~2KB

Next Steps

Angular Client

Use with Angular applications

Ky Client

Lightweight alternative with retry

Error Handling

Handle errors effectively

Interceptors

Add request/response interceptors

Get Started

Configuration

Core Plugins

HTTP Clients

Validators

State Management

Web Frameworks

Advanced

Installation

Basic Usage

Configuration

Client Options

Custom Axios Instance

Access Axios Instance

HTTP Methods

Response Format

Authentication

Bearer Token

Basic Authentication

API Key

Server-Sent Events

Request Cancellation

AbortController (Recommended)

Axios CancelToken

Advanced Features

Progress Monitoring

Response Type

Request Retry

Proxy Configuration

HTTP/HTTPS Agents

TypeScript Types

Comparison with Fetch Client

Next Steps

Angular Client

Ky Client

Error Handling

Interceptors

Build docs developers (and LLMs) love

Get Started

Configuration

Core Plugins

HTTP Clients

Validators

State Management

Web Frameworks

Advanced

​Installation

​Basic Usage

​Configuration

​Client Options

​Custom Axios Instance

​Access Axios Instance

​HTTP Methods

​Response Format

​Authentication

​Bearer Token

​Basic Authentication

​API Key

​Server-Sent Events

​Request Cancellation

​AbortController (Recommended)

​Axios CancelToken

​Advanced Features

​Progress Monitoring

​Response Type

​Request Retry

​Proxy Configuration

​HTTP/HTTPS Agents

​TypeScript Types

​Comparison with Fetch Client

​Next Steps

Angular Client

Ky Client

Error Handling

Interceptors

Build docs developers (and LLMs) love

Installation

Basic Usage

Configuration

Client Options

Custom Axios Instance

Access Axios Instance

HTTP Methods

Response Format

Authentication

Bearer Token

Basic Authentication

API Key

Server-Sent Events

Request Cancellation

AbortController (Recommended)

Axios CancelToken

Advanced Features

Progress Monitoring

Response Type

Request Retry

Proxy Configuration

HTTP/HTTPS Agents

TypeScript Types

Comparison with Fetch Client

Next Steps