This module is the lightest possible wrapper on top of node.js http
, but supporting these essential features:
url
key so there's no need to use url.parse
on the url when specifying optionsAll this in < 120 lines of code.
npm install simple-get
Note, all these examples also work in the browser with browserify.
Doesn't get easier than this:
const get = require('simple-get') get('http://example.com', function (err, res) { if (err) throw err console.log(res.statusCode) // 200 res.pipe(process.stdout) // `res` is a stream })
If you just want the data, and don't want to deal with streams:
const get = require('simple-get') get.concat('http://example.com', function (err, res, data) { if (err) throw err console.log(res.statusCode) // 200 console.log(data) // Buffer('this is the server response') })
For POST
, call get.post
or use option { method: 'POST' }
.
const get = require('simple-get') const opts = { url: 'http://example.com', body: 'this is the POST body' } get.post(opts, function (err, res) { if (err) throw err res.pipe(process.stdout) // `res` is a stream })
const get = require('simple-get') get({ url: 'http://example.com', method: 'POST', body: 'this is the POST body', // simple-get accepts all options that node.js `http` accepts // See: http://nodejs.org/api/http.html#http_http_request_options_callback headers: { 'user-agent': 'my cool app' } }, function (err, res) { if (err) throw err // All properties/methods from http.IncomingResponse are available, // even if a gunzip/inflate transform stream was returned. // See: http://nodejs.org/api/http.html#http_http_incomingmessage res.setTimeout(10000) console.log(res.headers) res.on('data', function (chunk) { // `chunk` is the decoded response, after it's been gunzipped or inflated // (if applicable) console.log('got a chunk of the response: ' + chunk) })) })
You can serialize/deserialize request and response with JSON:
const get = require('simple-get') const opts = { method: 'POST', url: 'http://example.com', body: { key: 'value' }, json: true } get.concat(opts, function (err, res, data) { if (err) throw err console.log(data.key) // `data` is an object })
You can set a timeout (in milliseconds) on the request with the timeout
option. If the request takes longer than timeout
to complete, then the entire request will fail with an Error
.
const get = require('simple-get') const opts = { url: 'http://example.com', timeout: 2000 // 2 second timeout } get(opts, function (err, res) {})
It's a good idea to set the 'user-agent'
header so the provider can more easily see how their resource is used.
const get = require('simple-get') const pkg = require('./package.json') get('http://example.com', { headers: { 'user-agent': `my-module/${pkg.version} (https://github.com/username/my-module)` } })
You can use the tunnel
module with the agent
option to work with proxies:
const get = require('simple-get') const tunnel = require('tunnel') const opts = { url: 'http://example.com', agent: tunnel.httpOverHttp({ proxy: { host: 'localhost' } }) } get(opts, function (err, res) {})
You can use the cookie
module to include cookies in a request:
const get = require('simple-get') const cookie = require('cookie') const opts = { url: 'http://example.com', headers: { cookie: cookie.serialize('foo', 'bar') } } get(opts, function (err, res) {})
You can use the form-data
module to create POST request with form data:
const fs = require('fs') const get = require('simple-get') const FormData = require('form-data') const form = new FormData() form.append('my_file', fs.createReadStream('/foo/bar.jpg')) const opts = { url: 'http://example.com', body: form } get.post(opts, function (err, res) {})
application/x-www-form-urlencoded
form data manually:const get = require('simple-get') const opts = { url: 'http://example.com', form: { key: 'value' } } get.post(opts, function (err, res) {})
You can use the oauth-1.0a
module to create a signed OAuth request:
const get = require('simple-get') const crypto = require('crypto') const OAuth = require('oauth-1.0a') const oauth = OAuth({ consumer: { key: process.env.CONSUMER_KEY, secret: process.env.CONSUMER_SECRET }, signature_method: 'HMAC-SHA1', hash_function: (baseString, key) => crypto.createHmac('sha1', key).update(baseString).digest('base64') }) const token = { key: process.env.ACCESS_TOKEN, secret: process.env.ACCESS_TOKEN_SECRET } const url = 'https://api.twitter.com/1.1/statuses/home_timeline.json' const opts = { url: url, headers: oauth.toHeader(oauth.authorize({url, method: 'GET'}, token)), json: true } get(opts, function (err, res) {})
You can use limiter to throttle requests. This is useful when calling an API that is rate limited.
const simpleGet = require('simple-get') const RateLimiter = require('limiter').RateLimiter const limiter = new RateLimiter(1, 'second') const get = (opts, cb) => limiter.removeTokens(1, () => simpleGet(opts, cb)) get.concat = (opts, cb) => limiter.removeTokens(1, () => simpleGet.concat(opts, cb)) var opts = { url: 'http://example.com' } get.concat(opts, processResult) get.concat(opts, processResult) function processResult (err, res, data) { if (err) throw err console.log(data.toString()) }
MIT. Copyright (c) Feross Aboukhadijeh.