diff --git a/README.md b/README.md index 9843757..c74435d 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,6 @@ Promise based HTTP client for the browser and node.js - Transform request and response data - Automatic transforms for JSON data - Client side support for protecting against [XSRF](http://en.wikipedia.org/wiki/Cross-site_request_forgery) -- Specify HTTP request headers ## Installing @@ -37,57 +36,57 @@ Performing a `GET` request ```js // 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); - }); + .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); - }); + params: { + ID: 12345 + } + }) + .then(function (response) { + console.log(response); + }) + .catch(function (response) { + console.log(response); + }); ``` Performing a `POST` request ```js axios.post('/user', { - firstName: 'Fred', - lastName: 'Flintstone' - }) - .then(function (response) { - console.log(response); - }) - .catch(function (response) { - console.log(response); - }); + firstName: 'Fred', + lastName: 'Flintstone' + }) + .then(function (response) { + console.log(response); + }) + .catch(function (response) { + console.log(response); + }); ``` Performing multiple concurrent requests ```js function getUserAccount() { - return axios.get('/user/12345'); + return axios.get('/user/12345'); } function getUserPermissions() { - return axios.get('/user/permissions/12345'); + return axios.get('/user/12345/permissions'); } axios.all([getUserAccount(), getUserPermissions()]) - .then(axios.spread(function (acct, perms) { - // Both requests are now complete - })); + .then(axios.spread(function (acct, perms) { + // Both requests are now complete + })); ``` ## axios API @@ -98,8 +97,8 @@ Requests can be made by passing the relevant config to `axios`. ```js axios({ - method: 'get', - url: '/user/12345' + method: 'get', + url: '/user/12345' }); ``` @@ -130,57 +129,57 @@ This is the available config options for making requests. Only the `url` is requ ```js { - // `url` is the server URL that will be used for the request - url: '/user', + // `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' + // The last function in the array must return a string or an ArrayBuffer + transformRequest: [function (data) { + // Do whatever you want to transform the data - // `method` is the request method to be used when making the request - method: 'get', // default + return data; + }], + + // `transformResponse` allows changes to the response data to be made before + // it is passed to then/catch + transformResponse: [function (data) { + // Do whatever you want to transform the data - // `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' - // The last function in the array must return a string or an ArrayBuffer - 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 then/catch - 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' - // When no `transformRequest` is set, must be a string, an ArrayBuffer or a hash - 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 + 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' + // When no `transformRequest` is set, must be a string, an ArrayBuffer or a hash + 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 } ``` @@ -190,17 +189,17 @@ The response for a request contains the following information. ```js { - // `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: {} + // `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: {} } ``` @@ -208,12 +207,31 @@ When using `then` or `catch`, you will receive the response as follows: ```js axios.get('/user/12345') - .then(function(response) { - console.log(response.data); - console.log(response.status); - console.log(response.headers); - console.log(response.config); - }); + .then(function(response) { + console.log(response.data); + console.log(response.status); + console.log(response.headers); + console.log(response.config); +}); +``` + +## Handling Errors + +```js +axios.get('/user/12345') + .catch(function (response) { + if (response instanceof Error) { + // Something happened in setting up the request that triggered an Error + console.log('Error', response.message); + } else { + // The request was made, but the server responded with a status code + // that falls out of the range of 2xx + console.log(response.data); + console.log(response.status); + console.log(response.headers); + console.log(response.config); + } + }); ``` ## Credits