Table of Contents

Features

Browser Support

Installing

$ npm install axios

$ bower install axios

$ yarn add axios

<scriptsrc="https://cdn.jsdelivr.net/npm/axios/dist/axios.min.js"></script>

<scriptsrc="https://unpkg.com/axios/dist/axios.min.js"></script>

Example

note: CommonJS usage

constaxios=require('axios').default;// axios.<method> will now provide autocomplete and parameter typings

constaxios=require('axios');// Make a request for a user with a given IDaxios.get('/user?ID=12345').then(function(response){// handle successconsole.log(response);}).catch(function(error){// handle errorconsole.log(error);}).then(function(){// always executed});// Optionally the request above could also be done asaxios.get('/user',{params:{ID:12345}}).then(function(response){console.log(response);}).catch(function(error){console.log(error);}).then(function(){// always executed});// Want to use async/await? Add the `async` keyword to your outer function/method.asyncfunctiongetUser(){try{constresponse=awaitaxios.get('/user?ID=12345');console.log(response);}catch(error){console.error(error);}}

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

functiongetUserAccount(){returnaxios.get('/user/12345');}functiongetUserPermissions(){returnaxios.get('/user/12345/permissions');}Promise.all([getUserAccount(),getUserPermissions()]).then(function(results){constacct=results[0];constperm=results[1];});

axios API

axios(config)

// Send a POST requestaxios({method:'post',url:'/user/12345',data:{firstName:'Fred',lastName:'Flintstone'}});

// GET request for remote image in node.jsaxios({method:'get',url:'http://bit.ly/2mTM3nY',responseType:'stream'}).then(function(response){response.data.pipe(fs.createWriteStream('ada_lovelace.jpg'))});

axios(url[, config])

// Send a GET request (default method)axios('/user/12345');

Request method aliases

axios.request(config)

axios.get(url[, config])

axios.delete(url[, config])

axios.head(url[, config])

axios.options(url[, config])

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

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

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

NOTE

Concurrency (Deprecated)

Creating an instance

axios.create([config])

constinstance=axios.create({baseURL:'https://some-domain.com/api/',timeout:1000,headers:{'X-Custom-Header':'foobar'}});

Instance methods

axios#request(config)

axios#get(url[, config])

axios#delete(url[, config])

axios#head(url[, config])

axios#options(url[, config])

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

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

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

axios#getUri([config])

Request Config

{// `url` is the server URL that will be used for the requesturl:'/user',// `method` is the request method to be used when making the requestmethod:'get',// default// `baseURL` will be prepended to `url` unless `url` is absolute.// It can be convenient to set `baseURL` for an instance of axios to pass relative URLs// to methods of that instance.baseURL:'https://some-domain.com/api/',// `transformRequest` allows changes to the request data before it is sent to the server// This is only applicable for request methods 'PUT', 'POST', 'PATCH' and 'DELETE'// The last function in the array must return a string or an instance of Buffer, ArrayBuffer,// FormData or Stream// You may modify the headers object.transformRequest:[function(data,headers){// Do whatever you want to transform the datareturndata;}],// `transformResponse` allows changes to the response data to be made before// it is passed to then/catchtransformResponse:[function(data){// Do whatever you want to transform the datareturndata;}],// `headers` are custom headers to be sentheaders:{'X-Requested-With':'XMLHttpRequest'},// `params` are the URL parameters to be sent with the request// Must be a plain object or a URLSearchParams objectparams:{ID:12345},// `paramsSerializer` is an optional function in charge of serializing `params`// (e.g. https://www.npmjs.com/package/qs, http://api.jquery.com/jquery.param/)paramsSerializer:function(params){returnQs.stringify(params,{arrayFormat:'brackets'})},// `data` is the data to be sent as the request body// Only applicable for request methods 'PUT', 'POST', 'DELETE , and 'PATCH'// When no `transformRequest` is set, must be of one of the following types:// - string, plain object, ArrayBuffer, ArrayBufferView, URLSearchParams// - Browser only: FormData, File, Blob// - Node only: Stream, Bufferdata:{firstName:'Fred'},// syntax alternative to send data into the body// method post// only the value is sent, not the keydata:'Country=Brasil&City=Belo Horizonte',// `timeout` specifies the number of milliseconds before the request times out.// If the request takes longer than `timeout`, the request will be aborted.timeout:1000,// default is `0` (no timeout)// `withCredentials` indicates whether or not cross-site Access-Control requests// should be made using credentialswithCredentials:false,// default// `adapter` allows custom handling of requests which makes testing easier.// Return a promise and supply a valid response (see lib/adapters/README.md).adapter:function(config){/* ... */},// `auth` indicates that HTTP Basic auth should be used, and supplies credentials.// This will set an `Authorization` header, overwriting any existing// `Authorization` custom headers you have set using `headers`.// Please note that only HTTP Basic auth is configurable through this parameter.// For Bearer tokens and such, use `Authorization` custom headers instead.auth:{username:'janedoe',password:'s00pers3cret'},// `responseType` indicates the type of data that the server will respond with// options are: 'arraybuffer', 'document', 'json', 'text', 'stream'//   browser only: 'blob'responseType:'json',// default// `responseEncoding` indicates encoding to use for decoding responses (Node.js only)// Note: Ignored for `responseType` of 'stream' or client-side requestsresponseEncoding:'utf8',// default// `xsrfCookieName` is the name of the cookie to use as a value for xsrf tokenxsrfCookieName:'XSRF-TOKEN',// default// `xsrfHeaderName` is the name of the http header that carries the xsrf token valuexsrfHeaderName:'X-XSRF-TOKEN',// default// `onUploadProgress` allows handling of progress events for uploads// browser onlyonUploadProgress:function(progressEvent){// Do whatever you want with the native progress event},// `onDownloadProgress` allows handling of progress events for downloads// browser onlyonDownloadProgress:function(progressEvent){// Do whatever you want with the native progress event},// `maxContentLength` defines the max size of the http response content in bytes allowed in node.jsmaxContentLength:2000,// `maxBodyLength` (Node only option) defines the max size of the http request content in bytes allowedmaxBodyLength:2000,// `validateStatus` defines whether to resolve or reject the promise for a given// HTTP response status code. If `validateStatus` returns `true` (or is set to `null`// or `undefined`), the promise will be resolved; otherwise, the promise will be// rejected.validateStatus:function(status){returnstatus>=200&&status<300;// default},// `maxRedirects` defines the maximum number of redirects to follow in node.js.// If set to 0, no redirects will be followed.maxRedirects:5,// default// `socketPath` defines a UNIX Socket to be used in node.js.// e.g. '/var/run/docker.sock' to send requests to the docker daemon.// Only either `socketPath` or `proxy` can be specified.// If both are specified, `socketPath` is used.socketPath:null,// default// `httpAgent` and `httpsAgent` define a custom agent to be used when performing http// and https requests, respectively, in node.js. This allows options to be added like// `keepAlive` that are not enabled by default.httpAgent:newhttp.Agent({keepAlive:true}),httpsAgent:newhttps.Agent({keepAlive:true}),// `proxy` defines the hostname, port, and protocol of the proxy server.// You can also define your proxy using the conventional `http_proxy` and// `https_proxy` environment variables. If you are using environment variables// for your proxy configuration, you can also define a `no_proxy` environment// variable as a comma-separated list of domains that should not be proxied.// Use `false` to disable proxies, ignoring environment variables.// `auth` indicates that HTTP Basic auth should be used to connect to the proxy, and// supplies credentials.// This will set an `Proxy-Authorization` header, overwriting any existing// `Proxy-Authorization` custom headers you have set using `headers`.// If the proxy server uses HTTPS, then you must set the protocol to `https`.proxy:{protocol:'https',host:'127.0.0.1',port:9000,auth:{username:'mikeymike',password:'rapunz3l'}},// `cancelToken` specifies a cancel token that can be used to cancel the request// (see Cancellation section below for details)cancelToken:newCancelToken(function(cancel){}),// `decompress` indicates whether or not the response body should be decompressed// automatically. If set to `true` will also remove the 'content-encoding' header// from the responses objects of all decompressed responses// - Node only (XHR cannot turn off decompression)decompress:true// default}

Response Schema

{// `data` is the response that was provided by the serverdata:{},// `status` is the HTTP status code from the server responsestatus:200,// `statusText` is the HTTP status message from the server responsestatusText:'OK',// `headers` the HTTP headers that the server responded with// All header names are lower cased and can be accessed using the bracket notation.// Example: `response.headers['content-type']`headers:{},// `config` is the config that was provided to `axios` for the requestconfig:{},// `request` is the request that generated this response// It is the last ClientRequest instance in node.js (in redirects)// and an XMLHttpRequest instance in the browserrequest:{}}

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

Config Defaults

Global axios defaults

axios.defaults.baseURL='https://api.example.com';// Important: If axios is used with multiple domains, the AUTH_TOKEN will be sent to all of them.// See below for an example using Custom instance defaults instead.axios.defaults.headers.common['Authorization']=AUTH_TOKEN;axios.defaults.headers.post['Content-Type']='application/x-www-form-urlencoded';

Custom instance defaults

// Set config defaults when creating the instanceconstinstance=axios.create({baseURL:'https://api.example.com'});// Alter defaults after instance has been createdinstance.defaults.headers.common['Authorization']=AUTH_TOKEN;

Config order of precedence

// Create an instance using the config defaults provided by the library// At this point the timeout config value is `0` as is the default for the libraryconstinstance=axios.create();// Override timeout default for the library// Now all requests using this instance will wait 2.5 seconds before timing outinstance.defaults.timeout=2500;// Override timeout for this request as it's known to take a long timeinstance.get('/longRequest',{timeout:5000});

Interceptors

// Add a request interceptoraxios.interceptors.request.use(function(config){// Do something before request is sentreturnconfig;},function(error){// Do something with request errorreturnPromise.reject(error);});// Add a response interceptoraxios.interceptors.response.use(function(response){// Any status code that lie within the range of 2xx cause this function to trigger// Do something with response datareturnresponse;},function(error){// Any status codes that falls outside the range of 2xx cause this function to trigger// Do something with response errorreturnPromise.reject(error);});

constmyInterceptor=axios.interceptors.request.use(function(){/*...*/});axios.interceptors.request.eject(myInterceptor);

constinstance=axios.create();instance.interceptors.request.use(function(){/*...*/});

Handling Errors

axios.get('/user/12345').catch(function(error){if(error.response){// The request was made and the server responded with a status code// that falls out of the range of 2xxconsole.log(error.response.data);console.log(error.response.status);console.log(error.response.headers);}elseif(error.request){// The request was made but no response was received// `error.request` is an instance of XMLHttpRequest in the browser and an instance of// http.ClientRequest in node.jsconsole.log(error.request);}else{// Something happened in setting up the request that triggered an Errorconsole.log('Error',error.message);}console.log(error.config);});

axios.get('/user/12345',{validateStatus:function(status){returnstatus<500;// Resolve only if the status code is less than 500}})

axios.get('/user/12345').catch(function(error){console.log(error.toJSON());});

Cancellation

constCancelToken=axios.CancelToken;constsource=CancelToken.source();axios.get('/user/12345',{cancelToken:source.token}).catch(function(thrown){if(axios.isCancel(thrown)){console.log('Request canceled',thrown.message);}else{// handle error}});axios.post('/user/12345',{name:'new name'},{cancelToken:source.token})// cancel the request (the message parameter is optional)source.cancel('Operation canceled by the user.');

constCancelToken=axios.CancelToken;letcancel;axios.get('/user/12345',{cancelToken:newCancelToken(functionexecutor(c){// An executor function receives a cancel function as a parametercancel=c;})});// cancel the requestcancel();

Using application/x-www-form-urlencoded format

Browser

constparams=newURLSearchParams();params.append('param1','value1');params.append('param2','value2');axios.post('/foo',params);

constqs=require('qs');axios.post('/foo',qs.stringify({'bar':123}));

importqsfrom'qs';constdata={'bar':123};constoptions={method:'POST',headers:{'content-type':'application/x-www-form-urlencoded'},data:qs.stringify(data),  url,};axios(options);

Node.js

Query string

constquerystring=require('querystring');axios.post('http://something.com/',querystring.stringify({foo:'bar'}));

consturl=require('url');constparams=newurl.URLSearchParams({foo:'bar'});axios.post('http://something.com/',params.toString());

NOTE

Form data

constFormData=require('form-data');constform=newFormData();form.append('my_field','my value');form.append('my_buffer',newBuffer(10));form.append('my_file',fs.createReadStream('/foo/bar.jpg'));axios.post('https://example.com',form,{headers:form.getHeaders()})

axios.interceptors.request.use(config=>{if(config.datainstanceofFormData){Object.assign(config.headers,config.data.getHeaders());}returnconfig;});

Semver

Promises

TypeScript

importaxiosfrom'axios';axios.get('/user?ID=12345');

Online one-click setup

Resources

Credits

License