The polite HTTP request library for node and the browser
OTHER License
There are a lot of JS libraries for making HTTP requests in JavaScript. Why use this one? Because it's awesome, that's why. And this is why it's awesome:
browserify and webpack users can simply npm install httpplease
.
Bower users can bower install httpplease
.
<script>
tag fans can grab the standalone build from the "browser-builds"
directory.
Minified and gzipped, the standalone browser build is <2K.
httpplease.get('http://example.com', function (err, res) {
// Do something with the result.
});
Alternatively, you can pass a request options object as the first parameter:
httpplease.get({url: 'http://example.com'}, function (err, res) {
// Do something with the result.
});
If you'd rather include the method in the object, that's okay too:
httpplease({method: 'GET', url: 'http://example.com'}, function (err, res) {
// Do something with the result.
});
You can create a new http function with default request object values:
var http = httpplease.defaults({method: 'GET', errorOn404: false});
http('http://example.com', function (err, res) {
// This request was made using the defaults specified above.
});
When you call one of the http functions (http
, http.get
, etc.), the result
is a Request object. This object can also be processed by plugins.
It has the same properties as the request options object you pass to the http
function (though properties that you didn't pass will be filled by defaults).
Those properties are:
In the event of an error, an error object will be passed as the first argument
to your callback. If the error is an HTTP error, it will have all of the
properties that a response object has (listed below), but will be a JS Error
object (which can be useful if relying on instanceof checks). It also has one
additional property—message
—which contains a description of the error.
The response object passed to your callback in the event of a successful request has the following properties:
httpplease supports plugins for changing how requests are made. Some plugins are built in:
Plugins are enabled with the use
method:
var json = require('httpplease/plugins/json');
httpplease = httpplease.use(json);
Or, if you're using the standalone build:
<script src="httpplease.js" type="text/javascript"></script>
<script src="httppleaseplugins.js" type="text/javascript"></script>
var json = httppleaseplugins.json;
httpplease = httpplease.use(json);
Notice that use
returns a new httpplease instance. This is so that you can
create multiple instances, each with their own plugins:
var http = httpplease.use(json);
http
.use(oldiexdomain)
.get('http://example.com', function (err, res) { ... }); // Uses "json" plugin and "oldiexdomain".
http.get('http://example.com', function (err, res) { ... }); // Only uses "json" plugin.
httpplease.get('http://example.com', function (err, res) { ... }); // No extra plugins are used.
You can use as many plugins as you want—either by passing multiple plugins to
use
or chaining calls:
var http = httpplease
.use(json, oldiexdomain, myPlugin)
.use(anotherPlugin);
In order to keep your builds as small as possible, most plugins aren't enabled
by default. (See the table above.) However, some small plugins are. If you
want to disable all plugins, use the bare()
method:
var http = httpplease.bare();
Like use()
, this method also returns a new httpplease instance so you can
continue to use the old object with the original plugins intact.
In addition to the bundled plugins, you can create your own. Plugins are simply objects that implement one or more of the following methods:
This project is mostly just a small wrapper around XMLHttpRequest and an (I hope) sensible structure for extending functionality. The reason it works on the server is because of driverdan's awesome node-XMLHttpRequest library—it's the secret sauce that makes the browser-focused design of httpplease possible!
I try to write good commit messages so the commit log should be very readable, but here's a summary of some notable changes.
onload
on onerror
where available since onreadystatechange
can'thttpplease/lib/plugins
to httpplease/plugins
abort
to request objectsetprotocol
pluginonload
and onerror
header()
to Request and Response objectserrorOn404
errorOn404
optiondefaults
a methodplugins
a method