Single-file HTTP client for NodeJS. With multipart support.
Pull request Compare This branch is 497 commits behind tomas:master.
Latest commit b5ae34a Mar 9, 2012 @tomas tomas Bump to 0.2.2
Permalink
Failed to load latest commit information.
bin
lib Default to name if buffer attachment doesn't contain filename Mar 9, 2012
test
.gitignore First commit Dec 11, 2011
README.md
package.json Bump to 0.2.2 Mar 9, 2012

README.md

Needle

Async HTTP client for NodeJS. Supports HTTPS, basic authentication, proxied requests, multipart form uploads and gzip/deflate compression. Really simple stuff, around ~250 lines of code.

Usage

var client = require('needle');

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

Callback receives three arguments: (error, response, body)

Options

  • timeout: Returns error if response takes more than X. Defaults to 10000 (10 secs).
  • compressed: Whether to ask for a deflated or gzipped response or not. Defaults to false.
  • parse: Whether to parse XML or JSON response bodies automagically. Defaults to true.
  • multipart: Enables multipart/form-data encoding. Defaults to false.
  • username: For HTTP basic auth.
  • password: For HTTP basic auth. Requires username to be passed, obviously.
  • agent: Uses an http.Agent of your choice, instead of the global (default) one.
  • proxy: Sends request via HTTP proxy. Eg. proxy: 'http://proxy.server.com:3128'

Examples

Simple GET.

client.get('http://www.google.com', function(err, resp, body){

  console.log("Got status code: " + resp.statusCode);

});

You can also skip the 'http://' part if you want, by the way.

HTTPS + querystring

client.get('https://www.google.com/search?q=syd+barrett', function(err, resp, body){

  // boom! works.

});

GET with options

var options = {
  username: 'you',
  password: 'secret',
  compressed: true,
  timeout: false,
  headers: {
    'X-Secret-Header': "Even more secret text"
  }
}

client.get('http://api.server.com', options, function(err, resp, body){

  // used HTTP auth

});

GET through proxy

client.get('http://search.npmjs.org', { proxy: 'http://localhost:1234' }, function(err, resp, body){

  // request passed through proxy

});

POST/PUT

var data = {
  foo: 'bar',
  nested: {
    params: {
      are: {
        also: 'supported'
      }
    }
  }
}

client.post('http://my.app.com', data, function(err, resp, body){

  // if you don't pass any data, needle will throw an exception.

});

Multipart POST: passing file path

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

var options = {
  multipart: true,
  timeout: 5000
}

client.post('http://my.other.app.com', data, options, function(err, resp, body){

  // in this case, if the request takes more than 5 seconds
  // the callback will return a [Socket closed] error

});

Multipart POST 2: 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' },
}

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

});

Credits

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

Copyright

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