node-httpreq
|
============
|
|
node-httpreq is a node.js library to do HTTP(S) requests the easy way
|
|
Do GET, POST, PUT, PATCH, DELETE, OPTIONS, upload files, use cookies, change headers, ...
|
|
## Install
|
|
You can install __httpreq__ using the Node Package Manager (npm):
|
|
npm install httpreq
|
|
## Simple example
|
```js
|
var httpreq = require('httpreq');
|
|
httpreq.get('http://www.google.com', function (err, res){
|
if (err) return console.log(err);
|
|
console.log(res.statusCode);
|
console.log(res.headers);
|
console.log(res.body);
|
console.log(res.cookies);
|
});
|
```
|
|
## How to use
|
|
* [httpreq.get(url, [options], callback)](#get)
|
* [httpreq.post(url, [options], callback)](#post)
|
* [httpreq.put(url, [options], callback)](#put)
|
* [httpreq.delete(url, [options], callback)](#delete)
|
* [httpreq.options(url, [options], callback)](#options)
|
* [Uploading files](#upload)
|
* [Downloading a binary file](#binary)
|
* [Downloading a file directly to disk](#download)
|
* [Sending a custom body](#custombody)
|
* [Using a http(s) proxy](#proxy)
|
* [httpreq.doRequest(options, callback)](#dorequest)
|
|
---------------------------------------
|
### httpreq.get(url, [options], callback)
|
<a name="get"></a>
|
|
__Arguments__
|
- url: The url to connect to. Can be http or https.
|
- options: (all are optional) The following options can be passed:
|
- parameters: an object of query parameters
|
- headers: an object of headers
|
- cookies: an array of cookies
|
- auth: a string for basic authentication. For example `username:password`
|
- binary: true/false (default: false), if true, res.body will a buffer containing the binary data
|
- allowRedirects: (default: __true__ , only with httpreq.get() ), if true, redirects will be followed
|
- maxRedirects: (default: __10__ ). For example 1 redirect will allow for one normal request and 1 extra redirected request.
|
- timeout: (default: __none__ ). Adds a timeout to the http(s) request. Should be in milliseconds.
|
- proxy, if you want to pass your request through a http(s) proxy server:
|
- host: eg: "192.168.0.1"
|
- port: eg: 8888
|
- protocol: (default: __'http'__ ) can be 'http' or 'https'
|
- rejectUnauthorized: validate certificate for request with HTTPS. [More here](http://nodejs.org/api/https.html#https_https_request_options_callback)
|
- callback(err, res): A callback function which is called when the request is complete. __res__ contains the headers ( __res.headers__ ), the http status code ( __res.statusCode__ ) and the body ( __res.body__ )
|
|
__Example without options__
|
|
```js
|
var httpreq = require('httpreq');
|
|
httpreq.get('http://www.google.com', function (err, res){
|
if (err) return console.log(err);
|
|
console.log(res.statusCode);
|
console.log(res.headers);
|
console.log(res.body);
|
});
|
```
|
|
__Example with options__
|
|
```js
|
var httpreq = require('httpreq');
|
|
httpreq.get('http://posttestserver.com/post.php', {
|
parameters: {
|
name: 'John',
|
lastname: 'Doe'
|
},
|
headers:{
|
'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:18.0) Gecko/20100101 Firefox/18.0'
|
},
|
cookies: [
|
'token=DGcGUmplWQSjfqEvmu%2BZA%2Fc',
|
'id=2'
|
]
|
}, function (err, res){
|
if (err){
|
console.log(err);
|
}else{
|
console.log(res.body);
|
}
|
});
|
```
|
---------------------------------------
|
### httpreq.post(url, [options], callback)
|
<a name="post"></a>
|
|
__Arguments__
|
- url: The url to connect to. Can be http or https.
|
- options: (all are optional) The following options can be passed:
|
- parameters: an object of post parameters (content-type is set to *application/x-www-form-urlencoded; charset=UTF-8*)
|
- json: if you want to send json directly (content-type is set to *application/json*)
|
- files: an object of files to upload (content-type is set to *multipart/form-data; boundary=xxx*)
|
- body: custom body content you want to send. If used, previous options will be ignored and your custom body will be sent. (content-type will not be set)
|
- headers: an object of headers
|
- cookies: an array of cookies
|
- auth: a string for basic authentication. For example `username:password`
|
- binary: true/false (default: __false__ ), if true, res.body will be a buffer containing the binary data
|
- allowRedirects: (default: __false__ ), if true, redirects will be followed
|
- maxRedirects: (default: __10__ ). For example 1 redirect will allow for one normal request and 1 extra redirected request.
|
- encodePostParameters: (default: __true__ ), if true, POST/PUT parameters names will be URL encoded.
|
- timeout: (default: none). Adds a timeout to the http(s) request. Should be in milliseconds.
|
- proxy, if you want to pass your request through a http(s) proxy server:
|
- host: eg: "192.168.0.1"
|
- port: eg: 8888
|
- protocol: (default: __'http'__ ) can be 'http' or 'https'
|
- rejectUnauthorized: validate certificate for request with HTTPS. [More here](http://nodejs.org/api/https.html#https_https_request_options_callback)
|
- callback(err, res): A callback function which is called when the request is complete. __res__ contains the headers ( __res.headers__ ), the http status code ( __res.statusCode__ ) and the body ( __res.body__ )
|
|
__Example without extra options__
|
|
```js
|
var httpreq = require('httpreq');
|
|
httpreq.post('http://posttestserver.com/post.php', {
|
parameters: {
|
name: 'John',
|
lastname: 'Doe'
|
}
|
}, function (err, res){
|
if (err){
|
console.log(err);
|
}else{
|
console.log(res.body);
|
}
|
});
|
```
|
|
__Example with options__
|
|
```js
|
var httpreq = require('httpreq');
|
|
httpreq.post('http://posttestserver.com/post.php', {
|
parameters: {
|
name: 'John',
|
lastname: 'Doe'
|
},
|
headers:{
|
'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:18.0) Gecko/20100101 Firefox/18.0'
|
},
|
cookies: [
|
'token=DGcGUmplWQSjfqEvmu%2BZA%2Fc',
|
'id=2'
|
]
|
}, function (err, res){
|
if (err){
|
console.log(err);
|
}else{
|
console.log(res.body);
|
}
|
});
|
```
|
|
---------------------------------------
|
### httpreq.put(url, [options], callback)
|
<a name="put"></a>
|
|
Same options as [httpreq.post(url, [options], callback)](#post)
|
|
---------------------------------------
|
<a name="delete" />
|
### httpreq.delete(url, [options], callback)
|
|
Same options as [httpreq.post(url, [options], callback)](#post)
|
|
---------------------------------------
|
<a name="options" />
|
### httpreq.options(url, [options], callback)
|
|
Same options as [httpreq.get(url, [options], callback)](#get) except for the ability to follow redirects.
|
|
---------------------------------------
|
<a name="upload" />
|
### Uploading files
|
|
You can still use ```httpreq.uploadFiles({url: 'url', files: {}}, callback)```, but it's easier to just use POST (or PUT):
|
|
__Example__
|
|
```js
|
var httpreq = require('httpreq');
|
|
httpreq.post('http://posttestserver.com/upload.php', {
|
parameters: {
|
name: 'John',
|
lastname: 'Doe'
|
},
|
files:{
|
myfile: __dirname + "/testupload.jpg",
|
myotherfile: __dirname + "/testupload.jpg"
|
}
|
}, function (err, res){
|
if (err) throw err;
|
});
|
```
|
|
---------------------------------------
|
<a name="binary"></a>
|
### Downloading a binary file
|
To download a binary file, just add __binary: true__ to the options when doing a get or a post.
|
|
__Example__
|
|
```js
|
var httpreq = require('httpreq');
|
|
httpreq.get('https://ssl.gstatic.com/gb/images/k1_a31af7ac.png', {binary: true}, function (err, res){
|
if (err){
|
console.log(err);
|
}else{
|
fs.writeFile(__dirname + '/test.png', res.body, function (err) {
|
if(err)
|
console.log("error writing file");
|
});
|
}
|
});
|
```
|
|
---------------------------------------
|
<a name="download"></a>
|
### Downloading a file directly to disk
|
To download a file directly to disk, use the download method provided.
|
|
Downloading is done using a stream, so the data is not stored in memory and directly saved to file.
|
|
__Example__
|
|
```js
|
var httpreq = require('httpreq');
|
|
httpreq.download(
|
'https://ssl.gstatic.com/gb/images/k1_a31af7ac.png',
|
__dirname + '/test.png'
|
, function (err, progress){
|
if (err) return console.log(err);
|
console.log(progress);
|
}, function (err, res){
|
if (err) return console.log(err);
|
console.log(res);
|
});
|
|
```
|
---------------------------------------
|
<a name="custombody"></a>
|
### Sending a custom body
|
Use the body option to send a custom body (eg. an xml post)
|
|
__Example__
|
|
```js
|
var httpreq = require('httpreq');
|
|
httpreq.post('http://posttestserver.com/post.php',{
|
body: '<?xml version="1.0" encoding="UTF-8"?>',
|
headers:{
|
'Content-Type': 'text/xml',
|
}},
|
function (err, res) {
|
if (err){
|
console.log(err);
|
}else{
|
console.log(res.body);
|
}
|
}
|
);
|
```
|
|
---------------------------------------
|
<a name="proxy"></a>
|
### Using a http(s) proxy
|
|
__Example__
|
|
```js
|
var httpreq = require('httpreq');
|
|
httpreq.post('http://posttestserver.com/post.php', {
|
proxy: {
|
host: '10.100.0.126',
|
port: 8888
|
}
|
}, function (err, res){
|
if (err){
|
console.log(err);
|
}else{
|
console.log(res.body);
|
}
|
});
|
```
|
|
---------------------------------------
|
### httpreq.doRequest(options, callback)
|
<a name="dorequest"></a>
|
|
httpreq.doRequest is internally used by httpreq.get() and httpreq.post(). You can use this directly. Everything is stays the same as httpreq.get() or httpreq.post() except that the following options MUST be passed:
|
- url: the url to post the files to
|
- method: 'GET', 'POST', 'PUT' or 'DELETE'
|
|
## Donate
|
|
If you like this module or you want me to update it faster, feel free to donate. It helps increasing my dedication to fixing bugs :-)
|
|
[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=AB3R2SUL53K7S)
|
