Home

Rem is an extensible HTTP client with middleware for Node.js and browsers. Built to power anything REST client, Rem comes with support for popular web services out of the box.

Tutorials

• Using Rem for authentication with Express
• Saving and restoring an authenticated API
• Using Rem with your API

API Reference

Rem Client

A Rem Client models an API. Calls for a client follow this format:

api[.format]([url fragments]).method([[query,] mime, body,] callback(err, data[, response]))

Defining a client

To set the default format, use format: 'type'.

var client = rem.createClient({format: 'json'});
client('http://archive.org/', {output: 'json'}).get(function (err, json) { ... }) // is JSON

To set a prefix for your URL, use base: 'http://path/'.

var client = rem.createClient({base: 'http://api.github.com'});
var client = rem.createClient('http://api.github.com'); // shorthand.
client('users/tcr/repos').get(function (err, json) { ... }) // http://api.github.com/users/tcr/repos

Making Calls

You can download different file formats:

var client = rem.createClient();
client.stream('http://google.com/').get(function (err, stream) { ... })
client.text('http://news.ycombinator.com/').get(function (err, html) { ... })
client.binary('http://placebear.com/200/200').get(function (err, image) { ... })
client.json('http://archive.org/', {output: 'json'}).get(function (err, json) { ... })
client.xml('http://waxy.org/links/index.xml').get(function (err, xml) { ... })

The URL can be multiple string arguments, which are concatenated as paths:

api('users', 'tcr', 'repos').get(...) // requests /users/tcr/repos
api('me/photos', {limit: 1}).get(...) // requests /me/photos?limit=1
api('me/photos').get({limit: 1}, ...) // also requests /me/photos?limit=1 for flexibility

Different HTTP methods take different parameters:

api(url).get([query], callback) // GET, HEAD, DELETE
api(url).post([[[query,] type,] data,] callback) // POST, PUT, PATCH

Specify form as a MIME type for application/x-www-form-urlencoded, or json for JSON encoding:

api(path).post('form', {first: 'Tim', last: 'Ryan'}, callback) // first=Tim&last=Ryan
api(path).post('json', {first: 'Tim', last: 'Ryan'}, callback) // {"first": "Tim", "last": "Ryan"}
api(path).post('image/png', buffer, callback) // binary buffer...
stream.pipe(api(path).post('image/png', callback)) // ...or stream

You can omit the type when an API has an uploadFormat set. All built-in APIs define this for you, so you have a consistent way to upload data:

twitter('statuses/update').post({status: 'Tweeting from Rem!'}, callback) // uploadFormat: "form"
github('user').patch({name": "monalisa octocat"}, callback) // uploadFormat: "json"

Classes

rem.ClientRequest

on 'pipe' // piped into other stream

req.headers
req.setHeader(key, value)
req.getHeader(key)
req.removeHeader(key)
req.url.protocol
req.url.auth
req.url.hostname
req.url.port
req.url.pathname
req.url.query
req.url.hash
req.url.getHost()
req.url.getPath()
req.url.toString()
req.url.parse(str)
req.write(chunk, [encoding])
req.end([data], [encoding])
req.send() // returns rem.ClientCall

rem.ClientResponse

emits 'data', 'end', 'close'

res.statusCode
res.httpVersion
res.headers
res.setEncoding([encoding])
res.pause()
res.resume()

OAuthentication

oauth.start([params], next(url, requestToken, requestSecret, results)) oauth.complete([verifier], requestToken, requestSecret, callback) oauth.complete([verifier], requestToken, requestSecret, callback)