needle

What is needle?

The needle npm package is a minimalistic HTTP client for Node.js, designed for simplicity and ease of use. It provides a straightforward interface for making HTTP requests and handling responses, supporting both callbacks and streams. It is lightweight and has built-in support for multipart form-data, which makes it suitable for file uploads and other form-related tasks.

What are needle's main functionalities?

Making HTTP GET requests

This feature allows you to perform HTTP GET requests to retrieve data from a specified URL. The callback function receives an error object and the response object, which includes the status code and the response body.

const needle = require('needle');

needle.get('https://api.example.com', (error, response) => {
  if (!error && response.statusCode == 200)
    console.log(response.body);
});

Making HTTP POST requests

This feature is used to send HTTP POST requests with data to a specified URL. The data can be an object, which needle will automatically encode as application/x-www-form-urlencoded or multipart/form-data, depending on the content.

const needle = require('needle');

const data = { foo: 'bar' };
needle.post('https://api.example.com', data, (error, response) => {
  if (!error && response.statusCode == 200)
    console.log(response.body);
});

Streaming support

Needle supports streaming, which allows you to pipe the response stream to another stream, such as a file write stream. This is useful for handling large amounts of data or streaming file downloads.

const needle = require('needle');
const fs = require('fs');

const stream = needle.get('https://api.example.com/stream');
stream.pipe(fs.createWriteStream('output.txt'));

Handling multipart form-data

Needle can handle multipart form-data, which is often used for file uploads. The data object can include file buffers, streams, or paths, and needle will handle the multipart encoding for you.

const needle = require('needle');

const data = {
  file: { file: 'path/to/file.jpg', content_type: 'image/jpeg' },
  other_field: 'value'
};

needle.post('https://api.example.com/upload', data, { multipart: true }, (error, response) => {
  if (!error && response.statusCode == 200)
    console.log('Upload successful');
});

Other packages similar to needle

axios

Axios is a promise-based HTTP client for the browser and Node.js. It provides a rich set of features like interceptors, automatic JSON data transformation, and cancellation. Compared to needle, axios is more feature-rich and has a larger footprint.

request

Request is a simplified HTTP request client that offers a wide range of features including OAuth signing, form uploads, and cookies. It is more complex and heavier than needle but has been deprecated as of 2020.

got

Got is a human-friendly and powerful HTTP request library for Node.js. It supports promises and async/await, streams, retries, and more. Got is more comprehensive than needle and is designed to be a more modern alternative with a focus on simplicity and composability.

node-fetch

Node-fetch is a light-weight module that brings the Fetch API to Node.js. It is a minimal and straightforward API that closely mirrors the browser's fetch API. Compared to needle, node-fetch is more aligned with web standards.

superagent

Superagent is a small progressive client-side HTTP request library, and Node.js module with the same API, sporting many high-level HTTP client features. It is more expressive than needle and includes features like a fluent API, chaining, and more.

README

Needle

The leanest and most handsome HTTP client in the Nodelands. With only two dependencies, it supports:

• HTTP and HTTPS requests
• Basic & Digest auth
• Forwarding via proxy
• Multipart form-data (e.g. file uploads)
• Gzip/deflate compression
• Automatic XML & JSON parsing
• 301/302 redirect following
• Decodes non-UTF-8 content.

Ideal for performing simple, quick HTTP requests in Node.js. If you need OAuth, AWS support or anything fancier, you should check out mikeal's request module.

Install

npm install needle

Usage

var needle = require('needle');

needle.get('http://www.google.com', function(error, response) {
  console.log('Got status code: ' + response.statusCode);
  console.log(response.body);
});

Methods

needle.get(url, [options], callback);
needle.head(url, [options], callback);
needle.post(url, data, [options], callback);
needle.put(url, data, [options], callback);
needle.delete(url, data, [options], callback);

// and a generic one
needle.request(method, url, data, [options], callback);

Callback receives (error, response, body). You can also access the body through response.body. If a JSON is received and parsing is enabled, both body and response.body will contain a Javascript object instead of the original response string.

Streaming

Needle returns the response stream, which means you can pipe it to your heart's content.

needle.get('google.com/images/logo.png').pipe(fs.createWriteStream('logo.png'));

For more examples, scroll down exactly seven turns of your mousewheel. Perhaps eight.

Request options

• timeout : Returns error if no response received in X milisecs. Defaults to 10000 (10 secs). 0 means no timeout.
• follow : Number of redirects to follow. false means don't follow any (default), true means 10.
• multipart : Enables multipart/form-data encoding. Defaults to false. Use it when uploading files.
• proxy : Forwards request through HTTP(s) proxy. Eg. proxy: 'http://proxy.server.com:3128'
• agent : Uses an http.Agent of your choice, instead of the global, default one.
• headers : Object containing custom HTTP headers for request. Overrides defaults described below.
• auth : Determines what to do with provided username/password. Options are auto, digest or basic (default). auto will detect the type of authentication depending on the response headers.
• json : When true, sets content type to application/json and sends request body as JSON string, instead of a query string.

Response options

• decode : Whether to decode the text responses to UTF-8, if Content-Type header shows a different charset. Defaults to true.
• parse : Whether to parse XML or JSON response bodies automagically. Defaults to true.
• output : Dump response output to file. This occurs after parsing and charset decoding is done.

Note: To stay light on dependencies, Needle doesn't include the xml2js module used for XML parsing. To enable it, simply do npm install xml2js.

HTTP Header options

These are basically shortcuts to the headers option described above.

• compressed: If true, sets 'Accept-Encoding' header to 'gzip,deflate', and inflates content if zipped. Defaults to false.
• username : For HTTP basic auth.
• password : For HTTP basic auth. Requires username to be passed, obviously.
• accept : Sets 'Accept' HTTP header. Defaults to */*.
• connection: Sets 'Connection' HTTP header. Defaults to close.
• user_agent: Sets the 'User-Agent' HTTP header. Defaults to Needle/{version} (Node.js {node_version}).

Node.js TLS Options

These options are passed directly to https.request if present. Taken from the original documentation:

• pfx: Certificate, Private key and CA certificates to use for SSL.
• key: Private key to use for SSL.
• passphrase: A string of passphrase for the private key or pfx.
• cert: Public x509 certificate to use.
• ca: An authority certificate or array of authority certificates to check the remote host against.
• ciphers: A string describing the ciphers to use or exclude.
• rejectUnauthorized: If true, the server certificate is verified against the list of supplied CAs. An 'error' event is emitted if verification fails. Verification happens at the connection level, before the HTTP request is sent.
• secureProtocol: The SSL method to use, e.g. SSLv3_method to force SSL version 3.

Examples

GET with querystring

needle.get('http://www.google.com/search?q=syd+barrett', function(err, resp) {
  if (!err && resp.statusCode == 200)
    console.log(resp.body); // prints HTML
});

HTTPS GET with Basic Auth

needle.get('https://api.server.com', { username: 'you', password: 'secret' },
  function(err, resp) {
    // used HTTP auth
});

Digest Auth

needle.get('other.server.com', { username: 'you', password: 'secret', auth: 'digest' }, 
  function(err, resp, body) {
    // needle prepends 'http://' to your URL, if missing
});

Custom headers, deflate

var options = {
  compressed : true,       // request a deflated response
  parse      : true,       // parse JSON
  headers    : {
    'X-Custom-Header': "Bumbaway atuna"
  }
}

needle.get('http://server.com/posts.json', options, function(err, resp, body) {
  // body will contain a JSON.parse(d) object
  // if parsing fails, you'll simply get the original body
});

GET XML object

needle.get('https://news.ycombinator.com/rss', function(err, resp, body) {
  // if xml2js is installed, you'll get a nice object containing the nodes in the RSS
});

GET binary, output to file

needle.get('http://upload.server.com/tux.png', { output: '/tmp/tux.png' }, function(err, resp, body) {
  // you can dump any response to a file, not only binaries.
});

GET through proxy

needle.get('http://search.npmjs.org', { proxy: 'http://localhost:1234' }, function(err, resp, body) {
  // request passed through proxy
});

Simple POST

needle.post('https://my.app.com/endpoint', 'foo=bar', function(err, resp, body) {
  // you can pass params as a string or as an object
});

PUT with data object

var nested = {
  params: {
    are: {
      also: 'supported'
    }
  }
}

needle.put('https://api.app.com/v2', nested, function(err, resp, body) {
  // if you don't pass any data, needle will throw an exception.
});

File upload using multipart, passing file path

var data = {
  foo: 'bar',
  image: { file: '/home/tomas/linux.png', content_type: 'image/png' }
}

needle.post('http://my.other.app.com', data, { multipart: true }, function(err, resp, body) {
  // needle will read the file and include it in the form-data as binary
});

Multipart POST, passing data buffer

var buffer = fs.readFileSync('/path/to/package.zip');

var data = {
  zip_file: {
    buffer       : buffer,
    filename     : 'mypackage.zip',
    content_type : 'application/octet-stream'
  },
}

needle.post('http://somewhere.com/over/the/rainbow', data, { multipart: true }, function(err, resp, body) {
  // if you see, when using buffers we need to pass the filename for the multipart body.
  // you can also pass a filename when using the file path method, in case you want to override
  // the default filename to be received on the other end.
});

Multipart with custom Content-Type

var data = {
  token: 'verysecret',
  payload: {
    value: JSON.stringify({ title: 'test', version: 1 }),
    content_type: 'application/json'
  }
}

needle.post('http://test.com/', data, { timeout: 5000, multipart: true }, function(err, resp, body) {
  // in this case, if the request takes more than 5 seconds
  // the callback will return a [Socket closed] error
});

Credits

Written by Tomás Pollak, with the help of contributors.

Copyright

(c) 2013 Fork Ltd. Licensed under the MIT license.