npm-axios

1
# HTTP Client and Requests
2

3
Core HTTP client functionality providing a comprehensive, Promise-based interface for making HTTP requests in both browser and Node.js environments.
4

5
## Capabilities
6

7
### Main Axios Instance
8

9
The default axios instance that can be called as a function or used as an object with method properties.
10

11
```javascript { .api }
12
/**
13
 * Make HTTP request using configuration object
14
 * @param config - Complete request configuration
15
 * @returns Promise resolving to response object
16
 */
17
axios(config: AxiosRequestConfig): Promise<AxiosResponse>;
18

19
/**
20
 * Make HTTP request with URL and optional configuration
21
 * @param url - Request URL
22
 * @param config - Optional request configuration
23
 * @returns Promise resolving to response object
24
 */
25
axios(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse>;
26
```
27

28
**Usage Examples:**
29

30
```javascript
31
import axios from 'axios';
32

33
// Request with config object
34
const response = await axios({
35
  method: 'get',
36
  url: 'https://api.example.com/users',
37
  timeout: 5000,
38
  headers: {
39
    'Authorization': 'Bearer token123'
40
  }
41
});
42

43
// Request with URL and config
44
const response = await axios('https://api.example.com/users', {
45
  method: 'post',
46
  data: { name: 'John', email: 'john@example.com' }
47
});
48
```
49

50
### HTTP Method Aliases - GET-like Methods
51

52
HTTP methods that typically don't send request body data.
53

54
```javascript { .api }
55
/**
56
 * Make GET request
57
 * @param url - Request URL
58
 * @param config - Optional request configuration
59
 * @returns Promise resolving to response object
60
 */
61
axios.get(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse>;
62

63
/**
64
 * Make DELETE request
65
 * @param url - Request URL  
66
 * @param config - Optional request configuration
67
 * @returns Promise resolving to response object
68
 */
69
axios.delete(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse>;
70

71
/**
72
 * Make HEAD request
73
 * @param url - Request URL
74
 * @param config - Optional request configuration
75
 * @returns Promise resolving to response object
76
 */
77
axios.head(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse>;
78

79
/**
80
 * Make OPTIONS request
81
 * @param url - Request URL
82
 * @param config - Optional request configuration
83
 * @returns Promise resolving to response object
84
 */
85
axios.options(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse>;
86
```
87

88
**Usage Examples:**
89

90
```javascript
91
// GET request with query parameters
92
const users = await axios.get('https://api.example.com/users', {
93
  params: { page: 1, limit: 10 }
94
});
95

96
// DELETE request with authorization
97
const result = await axios.delete('https://api.example.com/users/123', {
98
  headers: { 'Authorization': 'Bearer token123' }
99
});
100

101
// HEAD request to check if resource exists
102
const headResponse = await axios.head('https://api.example.com/users/123');
103
console.log(headResponse.status); // 200 if exists, 404 if not
104

105
// OPTIONS request to check allowed methods
106
const optionsResponse = await axios.options('https://api.example.com/users');
107
console.log(optionsResponse.headers['allow']);
108
```
109

110
### HTTP Method Aliases - POST-like Methods
111

112
HTTP methods that send data in the request body.
113

114
```javascript { .api }
115
/**
116
 * Make POST request
117
 * @param url - Request URL
118
 * @param data - Data to send in request body
119
 * @param config - Optional request configuration
120
 * @returns Promise resolving to response object
121
 */
122
axios.post(url: string, data?: any, config?: AxiosRequestConfig): Promise<AxiosResponse>;
123

124
/**
125
 * Make PUT request
126
 * @param url - Request URL
127
 * @param data - Data to send in request body
128
 * @param config - Optional request configuration
129
 * @returns Promise resolving to response object
130
 */
131
axios.put(url: string, data?: any, config?: AxiosRequestConfig): Promise<AxiosResponse>;
132

133
/**
134
 * Make PATCH request
135
 * @param url - Request URL
136
 * @param data - Data to send in request body
137
 * @param config - Optional request configuration
138
 * @returns Promise resolving to response object
139
 */
140
axios.patch(url: string, data?: any, config?: AxiosRequestConfig): Promise<AxiosResponse>;
141
```
142

143
**Usage Examples:**
144

145
```javascript
146
// POST request with JSON data
147
const newUser = await axios.post('https://api.example.com/users', {
148
  name: 'Alice Johnson',
149
  email: 'alice@example.com',
150
  role: 'admin'
151
});
152

153
// PUT request to update entire resource
154
const updatedUser = await axios.put('https://api.example.com/users/123', {
155
  name: 'Alice Smith',
156
  email: 'alice.smith@example.com',
157
  role: 'moderator'
158
});
159

160
// PATCH request to partially update resource
161
const patchedUser = await axios.patch('https://api.example.com/users/123', {
162
  role: 'admin'
163
});
164
```
165

166
### Form Data Methods
167

168
Convenience methods for sending form data with automatic `multipart/form-data` content type.
169

170
```javascript { .api }
171
/**
172
 * Make POST request with form data
173
 * @param url - Request URL
174
 * @param data - Form data to send
175
 * @param config - Optional request configuration
176
 * @returns Promise resolving to response object
177
 */
178
axios.postForm(url: string, data?: any, config?: AxiosRequestConfig): Promise<AxiosResponse>;
179

180
/**
181
 * Make PUT request with form data
182
 * @param url - Request URL
183
 * @param data - Form data to send
184
 * @param config - Optional request configuration
185
 * @returns Promise resolving to response object
186
 */
187
axios.putForm(url: string, data?: any, config?: AxiosRequestConfig): Promise<AxiosResponse>;
188

189
/**
190
 * Make PATCH request with form data
191
 * @param url - Request URL
192
 * @param data - Form data to send
193
 * @param config - Optional request configuration
194
 * @returns Promise resolving to response object
195
 */
196
axios.patchForm(url: string, data?: any, config?: AxiosRequestConfig): Promise<AxiosResponse>;
197
```
198

199
**Usage Examples:**
200

201
```javascript
202
// Post form data with file upload
203
const formData = new FormData();
204
formData.append('name', 'John Doe');
205
formData.append('avatar', fileInput.files[0]);
206

207
const response = await axios.postForm('https://api.example.com/users', formData);
208

209
// Post object data as form (automatically converted)
210
const response = await axios.postForm('https://api.example.com/users', {
211
  name: 'Jane Doe',
212
  email: 'jane@example.com'
213
});
214
```
215

216
### Core Request Method
217

218
The underlying request method used by all HTTP method aliases.
219

220
```javascript { .api }
221
/**
222
 * Core request method with full configuration support
223
 * @param config - Complete request configuration
224
 * @returns Promise resolving to response object  
225
 */
226
axios.request(config: AxiosRequestConfig): Promise<AxiosResponse>;
227
```
228

229
**Usage Examples:**
230

231
```javascript
232
// Custom request with full configuration
233
const response = await axios.request({
234
  method: 'get',
235
  url: 'https://api.example.com/data',
236
  timeout: 10000,
237
  headers: {
238
    'Accept': 'application/json',
239
    'User-Agent': 'MyApp/1.0'
240
  },
241
  params: { format: 'json' },
242
  validateStatus: (status) => status < 500
243
});
244
```
245

246
### URI Builder
247

248
Build complete URI from configuration without making a request.
249

250
```javascript { .api }
251
/**
252
 * Build URI from configuration object
253
 * @param config - Request configuration with URL components
254
 * @returns Complete URI string
255
 */
256
axios.getUri(config?: AxiosRequestConfig): string;
257
```
258

259
**Usage Examples:**
260

261
```javascript
262
// Build URI with query parameters
263
const uri = axios.getUri({
264
  url: '/users',
265
  baseURL: 'https://api.example.com',
266
  params: { page: 2, limit: 50 }
267
});
268
console.log(uri); // https://api.example.com/users?page=2&limit=50
269

270
// Build URI for complex request
271
const uri = axios.getUri({
272
  method: 'post',
273
  baseURL: 'https://api.example.com',
274
  url: '/users',
275
  params: { include: 'profile' }
276
});
277
```
278

279
### Instance Creation
280

281
Create new axios instances with custom default configuration.
282

283
```javascript { .api }
284
/**
285
 * Create new axios instance with custom defaults
286
 * @param config - Default configuration for the instance
287
 * @returns New axios instance
288
 */
289
axios.create(config?: AxiosRequestConfig): AxiosInstance;
290
```
291

292
**Usage Examples:**
293

294
```javascript
295
// Create instance with base URL and default headers
296
const apiClient = axios.create({
297
  baseURL: 'https://api.example.com',
298
  timeout: 5000,
299
  headers: {
300
    'Authorization': 'Bearer your-token',
301
    'Content-Type': 'application/json'
302
  }
303
});
304

305
// Use instance like main axios
306
const users = await apiClient.get('/users');
307
const newUser = await apiClient.post('/users', userData);
308

309
// Create instance for different API
310
const authClient = axios.create({
311
  baseURL: 'https://auth.example.com',
312
  timeout: 3000
313
});
314
```
315

316
## Response Object Structure
317

318
All HTTP methods return a Promise that resolves to an AxiosResponse object:
319

320
```javascript { .api }
321
interface AxiosResponse<T = any, D = any> {
322
  /** Response data (parsed JSON or raw data based on responseType) */
323
  data: T;
324
  /** HTTP status code */
325
  status: number;
326
  /** HTTP status message */
327
  statusText: string;
328
  /** Response headers */
329
  headers: AxiosResponseHeaders;
330
  /** Request configuration that generated this response */
331
  config: AxiosRequestConfig<D>;
332
  /** Platform-specific request object (XMLHttpRequest or Node.js request) */
333
  request?: any;
334
}
335
```
336

337
**Usage Examples:**
338

339
```javascript
340
const response = await axios.get('https://api.example.com/users/123');
341

342
console.log(response.data);        // User object or data
343
console.log(response.status);      // 200, 404, etc.
344
console.log(response.statusText);  // 'OK', 'Not Found', etc.  
345
console.log(response.headers);     // Response headers object
346
console.log(response.config);      // Request configuration used
347
```
348

349
## TypeScript Generic Support
350

351
Axios supports TypeScript generics for type-safe request and response handling:
352

353
```typescript { .api }
354
interface AxiosInstance {
355
  <T = any, R = AxiosResponse<T>, D = any>(config: AxiosRequestConfig<D>): Promise<R>;
356
  <T = any, R = AxiosResponse<T>, D = any>(url: string, config?: AxiosRequestConfig<D>): Promise<R>;
357
  
358
  get<T = any, R = AxiosResponse<T>, D = any>(url: string, config?: AxiosRequestConfig<D>): Promise<R>;
359
  post<T = any, R = AxiosResponse<T>, D = any>(url: string, data?: D, config?: AxiosRequestConfig<D>): Promise<R>;
360
  put<T = any, R = AxiosResponse<T>, D = any>(url: string, data?: D, config?: AxiosRequestConfig<D>): Promise<R>;
361
  patch<T = any, R = AxiosResponse<T>, D = any>(url: string, data?: D, config?: AxiosRequestConfig<D>): Promise<R>;
362
  delete<T = any, R = AxiosResponse<T>, D = any>(url: string, config?: AxiosRequestConfig<D>): Promise<R>;
363
  head<T = any, R = AxiosResponse<T>, D = any>(url: string, config?: AxiosRequestConfig<D>): Promise<R>;
364
  options<T = any, R = AxiosResponse<T>, D = any>(url: string, config?: AxiosRequestConfig<D>): Promise<R>;
365
  postForm<T = any, R = AxiosResponse<T>, D = any>(url: string, data?: D, config?: AxiosRequestConfig<D>): Promise<R>;
366
  putForm<T = any, R = AxiosResponse<T>, D = any>(url: string, data?: D, config?: AxiosRequestConfig<D>): Promise<R>;
367
  patchForm<T = any, R = AxiosResponse<T>, D = any>(url: string, data?: D, config?: AxiosRequestConfig<D>): Promise<R>;
368
}
369
```
370

371
**TypeScript Usage Examples:**
372

373
```typescript
374
import axios, { AxiosResponse } from 'axios';
375

376
interface User {
377
  id: number;
378
  name: string;
379
  email: string;
380
}
381

382
interface CreateUserData {
383
  name: string;
384
  email: string;
385
}
386

387
// Type-safe GET request
388
const response: AxiosResponse<User> = await axios.get<User>('/users/123');
389
const user: User = response.data; // Type-safe access
390

391
// Type-safe POST request
392
const newUser = await axios.post<User, AxiosResponse<User>, CreateUserData>(
393
  '/users',
394
  { name: 'John', email: 'john@example.com' }
395
);
396
```