How to make HTTP Requests using Needle in Node.js

Needle is a streamable HTTP client for making quick HTTP requests in a Node.js application to consume RESTful web services, uploading and downloading streams of data, etc.

In this tutorial, we'll discuss how to use Needle to send HTTP requests in the Node.js application. For all our examples, we will use dummy Reqres REST API to simulate real application scenarios.

Installation

Depending on your package manager, you can install the Needle by using either npm:

$ npm install needle --save

or yarn:

$ yarn add needle

Needle API

Needle supports both promises and traditional callbacks for making HTTP requests. You can also stream the data by skipping the callback.

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

// using promises
needle('get', 'https://reqres.in/api/users')
  .then(res => {
    console.log(res.body)
  })
  .catch(err => {
    console.error(err)
  })

// using traditional callback
needle.get('https://reqres.in/api/users', (err, res, body) => {
  if (err) {
    console.error(err)
  }

  console.log(res.body) // or just `body` as it is an alias of `res.body`
})

// skip callback, using streams
let out = fs.createWriteStream('got.jpg')
needle
  .get('https://i.imgur.com/7zTMFOe.jpg')
  .pipe(out)
  .on('finish', () => {
    console.log('pipe done')
  })

As you can see above, calling needle() directly returns a JavaScript promise. Just like Axios, Needle also provides aliases for all supported HTTP request methods: needle.get(), needle.post(), needle.put(), and so on.

These aliases return a readable stream. Depending on the response's content-type, Needle automatically parses the response body to JSON or XML streams.

GET Request

The following code snippet shows how to use the needle.get() method to get a list of users:

const needle = require('needle')

needle.get('https://reqres.in/api/users', (err, res, body) => {
  if (err) {
    console.error(err)
  }
  console.log(body)
})

If you want to pass the query parameters, you can either append them to a URL like the following:

needle.get('https://www.google.com/search?q=needle', (err, res, body) => {
 if (err) {
   console.error(err)
 }
 console.log(body)
})

or use needle.request() method to pass parameters as an object:

needle.request('get', 'https://www.google.com/search', { q: 'needle' }, (err, res) => {
 if (err) {
   console.error(err)
 }
 console.log(res.body)
})

POST Request

You can send an HTTP post request using the needle.post() method:

const needle = require('needle')

needle.post(
 'https://reqres.in/api/users',
 {
   name: 'Atta',
   job: 'Freelance Developer'
 },
 (err, res) => {
   if (err) {
     console.error(err)
   }
   console.log(res.body)
 }
)

By default, the request body is sent as a query string. But you can pass json: true in options to set the content type to application/json, and send the request body as a JSON string:

const needle = require('needle')

needle.post(
  'https://reqres.in/api/users',
  {
    name: 'Atta',
    job: 'Freelance Developer'
  },
  { json: true },
  (err, res) => {
    if (err) {
      console.error(err)
    }
    console.log(res.body)
  }
)

PUT Request

Use the needle.put() method to send an HTTP put request:

const needle = require('needle')

needle.put(
  'https://reqres.in/api/users/2',
  {
    name: 'Atta',
    job: 'MEAN Stack Developer'
  },
  { json: true },
  (err, res) => {
    if (err) {
      console.error(err)
    }
    console.log(res.body)
  }
)

DELETE Request

Needle provides needle.delete() method to perform an HTTP delete request:

const needle = require('needle')

needle.delete('https://reqres.in/api/users/2', null, (err, res) => {
  if (err) {
    console.error(err)
  }
  console.log(res.statusCode)
})

Interested in learning more about HTTP clients in Node.js? Check out 7 Ways to Make HTTP Requests in Node.js tutorial.

Conclusion

Needle is a streamable HTTP client for Node.js that supports proxy, iconv, redirect following, cookie, deflate, and multi-part requests. With Needle, you can use promises and callbacks to perform HTTP requests.

For more configuration options, read Needle docs on GitHub.

✌️ Like this article? Follow me on Twitter and LinkedIn. You can also subscribe to RSS Feed.