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.

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]))

You can download different file formats:

var client = new rem.Client();
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) { ... })

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

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

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"

Request, Response

rem.ClientRequest

.headers
.setHeader(key, value)
.getHeader(key)
.removeHeader(key)
.url.protocol
.url.auth
.url.hostname
.url.port
.url.pathname
.url.query
.url.hash
.url.getHost()
.url.getPath()
.url.toString()
.url.parse()
.write(chunk, [encoding])
.end([data], [encoding])
.send() // returns rem.ClientCall
on 'pipe' // piped into other stream

rem.ClientResponse

.statusCode
.httpVersion
.headers
.setEncoding([encoding])
.pause()
.resume()
emits 'data', 'end', 'close'

OAuthentication

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