httpreq

What is httpreq?

The httpreq npm package is a module that provides a simple interface for making HTTP requests in Node.js. It is designed to make HTTP calls straightforward by handling the complexities of Node's native http module.

What are httpreq's main functionalities?

GET requests

This feature allows you to perform HTTP GET requests to retrieve data from a specified URL.

httpreq.get('http://example.com', function (err, res){
  if (err) return console.error(err);
  console.log(res.body);
});

POST requests

This feature enables you to send HTTP POST requests with parameters to a specified URL, which can be used for submitting form data or interacting with REST APIs.

httpreq.post('http://example.com', {
  parameters: {
    key1: 'value1',
    key2: 'value2'
  }
}, function (err, res){
  if (err) return console.error(err);
  console.log(res.body);
});

Custom headers

This feature allows you to set custom headers for your HTTP requests, which can be necessary for APIs that require specific headers for authentication or content negotiation.

httpreq.get('http://example.com', {
  headers: {
    'User-Agent': 'My Custom User Agent'
  }
}, function (err, res){
  if (err) return console.error(err);
  console.log(res.headers);
});

File uploads

This feature is used to upload files to a server. It supports multipart form data, which is commonly used for file uploads in web forms.

httpreq.post('http://example.com/upload', {
  files: {
    file1: '/path/to/file1.txt',
    file2: '/path/to/file2.jpg'
  }
}, function (err, res){
  if (err) return console.error(err);
  console.log(res.body);
});

Other packages similar to httpreq

axios

Axios is a popular HTTP client for the browser and Node.js. It provides a promise-based API and has a wide range of features including interceptors, automatic transforms for JSON data, and client-side protection against XSRF. It is often considered more feature-rich and modern compared to httpreq.

request

Request is a simplified HTTP request client that was very popular in the Node.js community but has been deprecated. It offered a simple interface for making all types of HTTP requests and supported features like OAuth signing, form uploads, and cookies. Despite its deprecation, it is still used for comparison due to its historical significance.

node-fetch

Node-fetch is a light-weight module that brings the Fetch API to Node.js. It is a window.fetch polyfill that aims to stay consistent with the browser's implementation of fetch. It is promise-based and is a good choice for users who prefer the Fetch API's approach to making HTTP requests.

got

Got is a human-friendly and powerful HTTP request library for Node.js. It provides a lot of features out of the box like retries, streams, and pagination, and has a more modern API using promises and async/await. It is considered a good alternative to httpreq with more advanced capabilities.

README

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

This module helps you fight TLS fingerprinting! See the shuffleCiphers option below.

Donate

If you've benefited from this module in any way, please consider donating!

Thank you for your support!

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)
• httpreq.post(url, [options], callback)
• httpreq.put(url, [options], callback)
• httpreq.delete(url, [options], callback)
• httpreq.options(url, [options], callback)
• Uploading files
• Downloading a binary file
• Downloading a file directly to disk
• Sending a custom body
• Using a http(s) proxy
• httpreq.doRequest(options, callback)

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.
  • ciphers: Change the TLS ciphers if needed.
  • shuffleCiphers: Set to true if you want to shuffle the TLS ciphers to fight TLS fingerprinting.
  • 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 + '/file1.jpg',
    myotherfile: __dirname + '/file2.jpg'
  }
}, function (err, res){
  if (err) throw err;
});

Example 2

In case you want to use the same form name for multiple files:

var httpreq = require('httpreq');

httpreq.post('http://posttestserver.com/upload.php', {
  parameters: {
    name: 'John',
    lastname: 'Doe'
  },
  files: {
    myfiles: [__dirname + '/file1.jpg', __dirname + '/file.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