Needle
![NPM](https://nodei.co/npm/needle.png)
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);
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
.
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);
});
HTTPS GET with Basic Auth
needle.get('https://api.server.com', { username: 'you', password: 'secret' },
function(err, resp) {
});
Digest Auth
needle.get('other.server.com', { username: 'you', password: 'secret', auth: 'digest' },
function(err, resp, body) {
});
var options = {
compressed : true,
parse : true,
headers : {
'X-Custom-Header': "Bumbaway atuna"
}
}
needle.get('http://server.com/posts.json', options, function(err, resp, body) {
});
GET XML object
needle.get('https://news.ycombinator.com/rss', function(err, resp, body) {
});
GET binary, output to file
needle.get('http://upload.server.com/tux.png', { output: '/tmp/tux.png' }, function(err, resp, body) {
});
GET through proxy
needle.get('http://search.npmjs.org', { proxy: 'http://localhost:1234' }, function(err, resp, body) {
});
Simple POST
needle.post('https://my.app.com/endpoint', 'foo=bar', function(err, resp, body) {
});
PUT with data object
var nested = {
params: {
are: {
also: 'supported'
}
}
}
needle.put('https://api.app.com/v2', nested, function(err, resp, body) {
});
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) {
});
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) {
});
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) {
});
Credits
Written by Tomás Pollak, with the help of contributors.
Copyright
(c) 2013 Fork Ltd. Licensed under the MIT license.