axios

What is axios?

Axios is a promise-based HTTP client for the browser and Node.js. It provides an easy-to-use API for sending asynchronous HTTP requests to REST endpoints and performing CRUD operations. It can be used to make XMLHttpRequests from the browser or HTTP requests from Node.js, supports the Promise API, and provides a way to intercept request and response, transform request and response data, and cancel requests.

What are axios's main functionalities?

Performing GET requests

This feature allows you to perform a GET request to retrieve data from a specified resource.

axios.get('/user?ID=12345').then(function (response) { console.log(response); }).catch(function (error) { console.log(error); });

Performing POST requests

This feature allows you to perform a POST request to send data to a server to create/update a resource.

axios.post('/user', { firstName: 'Fred', lastName: 'Flintstone' }).then(function (response) { console.log(response); }).catch(function (error) { console.log(error); });

Performing concurrent requests

This feature allows you to make multiple requests simultaneously.

axios.all([axios.get('/user/12345'), axios.get('/user/67890')]).then(axios.spread(function (acct, perms) { console.log(acct, perms); }));

Interceptors

This feature allows you to intercept requests or responses before they are handled by then or catch.

axios.interceptors.request.use(function (config) { config.headers.Authorization = AUTH_TOKEN; return config; }, function (error) { return Promise.reject(error); });

Creating instances

This feature allows you to create a new instance of axios with custom config defaults.

const instance = axios.create({ baseURL: 'https://api.example.com' }); instance.get('/users').then(function (response) { console.log(response); });

Other packages similar to axios

fetch

The Fetch API provides a JavaScript interface for accessing and manipulating parts of the HTTP pipeline, such as requests and responses. It is a modern alternative to XMLHttpRequest and is native to modern browsers. Unlike axios, it is not based on promises by default but can be used with promises.

superagent

Superagent is a light-weight progressive ajax API crafted for flexibility, readability, and a low learning curve after being frustrated with many of the existing request APIs. It is similar to axios but with a different API design and chainable methods.

got

Got is a human-friendly and powerful HTTP request library for Node.js. It is designed to be a simpler and more performant alternative to Node's native http module. Got offers stream support, promise APIs, and advanced features like retries and timeouts.

request

Request is a simplified HTTP request client 'simplified' with many features. It is one of the most popular HTTP client libraries but has been deprecated as of February 2020. It had a callback-based API, which is different from axios's promise-based API.

node-fetch

node-fetch is a light-weight module that brings the Fetch API to Node.js. It is an implementation of the window.fetch function for Node.js, aiming to provide a consistent API with the browser's fetch function. It is similar to axios in terms of promise-based requests but follows the Fetch API standard.

README

axios

Promise based HTTP client for the browser and node.js

Features

• Make XMLHttpRequests from the browser
• Make http requests from node.js
• Supports the Promise API
• Transform request and response data
• Automatic transforms for JSON data
• Client side support for protecting against XSRF
• Specify HTTP request headers

Installing

Using bower:

$ bower install axios

Using npm:

$ npm install axios

Compatibility

Tested to work with >=IE8, Chrome, Firefox, Safari, and Opera.

Example

Performing a GET request

// Make a request for a user with a given ID
axios.get('/user?ID=12345')
	.then(function (response) {
		console.log(response);
	})
	.catch(function (response) {
		console.log(response);
	});
	
// Optionally the request above could also be done as
axios.get('/user', {
		params: {
			ID: 12345
		}
	})
	.then(function (response) {
		console.log(response);
	})
	.catch(function (response) {
		console.log(response);
	});

Performing a POST request

axios.post('/user', {
		firstName: 'Fred',
		lastName: 'Flintstone'
	})
	.then(function (response) {
		console.log(response);
	})
	.catch(function (response) {
		console.log(response);
	});

Aliases are provided for success and error

axios.get('/user/12345')
	.success(function () {
		console.log('user found');
	})
	.error(function () {
		console.log('error finding user');
	});

Performing multiple concurrent requests

function getUserAccount() {
	return axios.get('/user/12345');
}

function getUserPermissions() {
	return axios.get('/user/permissions/12345');
}

axios.all([getUserAccount(), getUserPermissions()])
	.then(axios.spread(function (acct, perms) {
		// Both requests are now complete
	}));

axios API

Requests can be made by passing the relevant config to axios.

axios(config)

axios({
	method: 'get',
	url: '/user/12345'
});

Request method aliases

For convenience aliases have been provided for all supported request methods.

axios.get(url[, config])

axios.delete(url[, config])

axios.head(url[, config])

axios.post(url[, data[, config]])

axios.put(url[, data[, config]])

axios.patch(url[, data[, config]])

NOTE

When using the alias methods url, method, and data properties don't need to be specified in config.

Concurrency

Helper functions for dealing with concurrent requests.

axios.all(iterable)

axios.spread(callback)

Request API

This is the available config options for making requests. Only the url is required. Requests will default to GET if method is not specified.

{
	// `url` is the server URL that will be used for the request
	url: '/user',
	
	// `method` is the request method to be used when making the request
	method: 'get', // default
	
	// `transformRequest` allows changes to the request data before it is sent to the server
	// This is only applicable for request methods 'PUT', 'POST', and 'PATCH'
	transformRequest: [function (data) {
		// Do whatever you want to transform the data
		
		return data;
	}],
	
	// `transformResponse` allows changes to the response data to be made before
	// it is passed to the success/error handlers
	transformResponse: [function (data) {
		// Do whatever you want to transform the data
		
		return data;
	}],
	
	// `headers` are custom headers to be sent
	headers: {'X-Requested-With': 'XMLHttpRequest'},
	
	// `param` are the URL parameters to be sent with the request
	params: {
		ID: 12345
	},
	
	// `data` is the data to be sent as the request body
	// Only applicable for request methods 'PUT', 'POST', and 'PATCH'
	data: {
		firstName: 'Fred'
	},
	
	// `withCredentials` indicates whether or not cross-site Access-Control requests
	// should be made using credentials
	withCredentials: false, // default
	
	// `responseType` indicates the type of data that the server will respond with
	// options are 'arraybuffer', 'blob', 'document', 'json', 'text'
	responseType: 'json', // default
	
	// `xsrfCookieName` is the name of the cookie to use as a value for xsrf token
	xsrfCookieName: 'XSRF-TOKEN', // default
	
	// `xsrfHeaderName` is the name of the http header that carries the xsrf token value
	xsrfHeaderName: 'X-XSRF-TOKEN' // default
}

Response API

The response for a request contains the following information.

{
	// `data` is the response that was provided by the server
	data: {},
	
	// `status` is the HTTP status code from the server response
	status: 200,
	
	// `headers` the headers that the server responded with
	headers: {},
	
	// `config` is the config that was provided to `axios` for the request
	config: {}
}

When using then or catch, you will receive a single response object.

axios.get('/user/12345')
	.then(function(response) {
		console.log(response.data);
		console.log(response.status);
		console.log(response.headers);
		console.log(response.config);
	});

For either success or error, the response is broken up into individual arguments.

axios.get('/user/12345')
	.success(function (data, status, headers, config) {
		console.log(data);
		console.log(status);
		console.log(headers);
		console.log(config);
	});
}

Credits

axios is heavily inspired by the $http service provided in Angular. Ultimately axios is an effort to provide a standalone $http-like service for use outside of Angular.

axios uses the es6-promise polyfill by Jake Archibald. Until we can use ES6 Promises natively in all browsers, this polyfill is a life saver.

License

MIT