httpreq

    0.5.2 • Public • Published

    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, ...

    Donate

    Feel free to buy me a pizza 🍕

    Install

    You can install httpreq using the Node Package Manager (npm):

    npm install httpreq
    

    Simple example

    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);
    });

    Using await/async:

    var httpreq = require('httpreq');
    
    var res = await httpreq.get('http://www.google.com');
    
    console.log(res.statusCode);
    console.log(res.headers);
    console.log(res.body);
    console.log(res.cookies);

    Use with async/await

    This module has been updated to support async/await.

    In the following examples, simply omit the callback parameter and prepend it with await.

    Example:

    var httpreq = require('httpreq');
    
    var res = await httpreq.post('http://posttestserver.com/post.php', {
      parameters: {
        name: 'John',
        lastname: 'Doe'
      }
    });
    
    console.log(res.body);

    How to use


    httpreq.get(url, [options], callback)

    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
    • 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

    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

    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)

    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
    • 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

    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

    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)

    Same options as httpreq.post(url, [options], callback)


    ### httpreq.delete(url, [options], callback)

    Same options as httpreq.post(url, [options], callback)


    ### httpreq.options(url, [options], callback)

    Same options as httpreq.get(url, [options], callback) except for the ability to follow redirects.


    ### Uploading files

    You can still use httpreq.uploadFiles({url: 'url', files: {}}, callback), but it's easier to just use POST (or PUT):

    Example

    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;
    });

    Downloading a binary file

    To download a binary file, just add binary: true to the options when doing a get or a post.

    Example

    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");
        });
      }
    });

    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

    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);
    });

    When specifying the progress callback (3th parameter), you cannot use async/await.


    Sending a custom body

    Use the body option to send a custom body (eg. an xml post)

    Example

    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);
        }
      }
    );

    Using a http(s) proxy

    Example

    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)

    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'

    Run tests

    Install all depedencies with

    npm install

    Install mocha with

    npm install mocha -g

    Run tests:

    mocha test/tests.js

    Run the async/await tests:

    mocha test/tests-async.js

    Keywords

    none

    Install

    npm i httpreq

    DownloadsWeekly Downloads

    815,530

    Version

    0.5.2

    License

    MIT

    Unpacked Size

    34 kB

    Total Files

    5

    Last publish

    Collaborators

    • samdecrock