Package Exports
- needle
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (needle) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
Needle
The most handsome HTTP client in the Nodelands. Supports SSL, basic auth, requests via proxy, multipart form-data (e.g. file uploads), gzip/deflate compression and, as you would expect, follows redirects. Simple, nimble and to the point.
Usage
var needle = require('needle');
needle.get('http://www.google.com', function(err, resp, body){
console.log("Got status code: " + resp.statusCode);
});
Install
npm install needle
Options
timeout
: Returns error if response takes more than X milisecs. Defaults to10000
(10 secs).0
means no timeout.follow
: Whenfalse
, Needle won't follow redirects. Can also be a number ortrue
(the default, 10 max).compressed
: Whether to ask for a deflated or gzipped response or not. Defaults tofalse
.decode
: Whether to decode response to UTF-8 if Content-Type charset is different. Defaults totrue
.parse
: Whether to parse XML or JSON response bodies automagically. Defaults totrue
.multipart
: Enables multipart/form-data encoding. Defaults tofalse
.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
: Forwards request through HTTP proxy. Eg.proxy: 'http://proxy.server.com:3128'
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, [options], callback);
Callback receives three arguments: (error, response, body)
Examples
GET with querystring
needle.get('http://www.google.com/search?q=syd+barrett', function(err, resp, body){
if(!err && resp.statusCode == 200)
console.log(body); // prints HTML
});
HTTPS GET with Basic Auth
needle.get('https://api.server.com', { username: 'you', password: 'secret' },
function(err, resp, body){
// used HTTP auth
});
More options
var options = {
timeout: false,
compressed : true,
parse: true,
headers: {
'X-Custom-Header': "Bumbaway atuna"
}
}
needle.get('server.com/posts.json', options, function(err, resp, body){
// Needle prepends 'http://' to the URL if not found
});
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) 2012 Fork Ltd. Licensed under the MIT license.