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.

You might also like...

Digital Ocean

The simplest cloud platform for developers & teams. Start with a $200 free credit.

Buy me a coffee ☕

If you enjoy reading my articles and want to help me out paying bills, please consider buying me a coffee ($5) or two ($10). I will be highly grateful to you ✌️

Enter the number of coffees below:

✨ Learn to build modern web applications using JavaScript and Spring Boot

I started this blog as a place to share everything I have learned in the last decade. I write about modern JavaScript, Node.js, Spring Boot, core Java, RESTful APIs, and all things web development.

The newsletter is sent every week and includes early access to clear, concise, and easy-to-follow tutorials, and other stuff I think you'd enjoy! No spam ever, unsubscribe at any time.