rail
An enhanced HTTP/RESTful API Client
rail is an io.js/node.js HTTP client supporting https, http and http2.
A set of built-in plugins, currently featuring buffer
, cookies
, json
, redirect
, retry
, timeout
& validate
simplify making requests,
and a powerful event-driven plugin interface aids in the implementation of complex automated RESTful API calls.
The concept of a single request is extended to a possible series of requests further referenced as a call. This allows a seamless integration of redirect and authentication mechanisms that require multiple requests to satisfy the original one.
The API is mostly compatible with https.request()
and allows rail to be used as a drop-in replacement.
A completely transparent plugin integration enables scenarios with automated retries on upload stream errors, while still exhibiting a behavior similar to https.request()
.
rail works with io.js, node.js 0.10.x & 4.1.
Table of Contents
Installation
$ npm install rail --save-exact
Examples
URL only
Directly pass an URL that gets parsed into proto
, host
, port
& path
.
var RAIL = ; RAIL;
URL & Plugin Options
Again, only pass an URL, but this time as a property to allow passing of plugin options.
var RAIL = ; RAIL;
Request & Plugin Options
The usual way of supplying every parameter separately.
var RAIL = ; RAIL;
Custom Client
A custom client allows to define default options and configure a set of plugins for all calls made with that client.
var RAIL = ; var client = // set default request options request: host: 'github.com' // set default host // load & configure the buffer plugin buffer: default: true // buffer all responses by default // load & configure the json plugin json: auto: true // try to parse all responses with content-type equal to application/json // load & configure the redirect plugin redirect: limit: 3 // allow a maximum of three redirects for each call ; // load custom "my" pluginclient;
Now use the custom client the same way as the globalClient above
var call = client; call; call;
Use as a drop-in replacement
rail does not support the hostname
, auth
, localAddress
& socketPath
options, see rail.call() for more information.
When not using https, make sure to set the correct default protocol
var RAIL = ;RAILglobalClientproto = 'http';
... and then replace every call to http.request
with RAIL.call
.
Alternatively create a custom client with defaults & plugins configured to your needs.
Tests
- npm run lint Lint the code using eslint and these rules
- npm test Lint the code, run tests with mocha & collect coverage with istanbul
- detailed coverage report is available at
coverage/lcov-report/index.html
- detailed coverage report is available at
- npm run update Dependency update tests performed by next-update
- run
./tools/cross-test.sh
to test all relevant io.js/node.js versions, uses nvm
Coverage
Statements : 98.17% ( 803/818 )
Branches : 91.53% ( 378/413 )
Functions : 100% ( 109/109 )
Lines : 98.17% ( 803/818 )