httpplease

HTTP, Please
============

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:

* Designed for "isomorphic" JavaScript (supporting both client and server
with the same codebase)
* …but with a browser-driven focus that keeps in mind the limitations of
that environment (filesize, old IE)
* Extensible via a simple but powerful plugin system (which it dogfoods)
* Supports cross-domain requests in IE9 transparently with the
oldiexdomain plugin
* Supports promises (thenable/catchable request objects) with the
[promises plugin]

[browserify] and [webpack] users can simply npm install httpplease.

[Bower] users can bower install httpplease.



`

`javascript
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:

`javascript
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:

`javascript
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:

`javascript
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.


#### Custom Plugins

In addition to the bundled plugins, you can create your own. Plugins are simply
objects that implement one or more of the following methods:

Similar Projects

* [xhr] \(browser only\)
* [request] \(node only\)
* [httpify] \(wraps xhr and [request]\)

Thanks

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!

Changelog

I try to write good commit messages so the [commit log] should be very readable,
but here's a summary of some notable changes.

* v0.16.0
* Use onload on onerror where available since onreadystatechange can't
differentiate between 0 status code errors and successes
(matthewwithanm/react-inlinesvg#10)
* v0.15.0
* Rename "jsonparser" to "jsonresponse"
* Set Accept header in "jsonresponse" instead of "jsonrequest"
* Add "json" plugin that combines "jsonrequest" and "jsonresponse"
* v0.14.0
* Move plugins from httpplease/lib/plugins to httpplease/plugins
* v0.13.1
* Don't add Content-Type header if request has no body in jsonrequest
plugin. (This avoids an unneeded preflight request.)
* v0.13.0
* Add support for timeouts
* v0.12.0
* Add abort to request object
* v0.11.0
* Add setprotocol plugin
* v0.9.0
* Ignore request headers when using oldiexdomain
* Change when plugin methods are called
* v0.8.1
* Add Accept header if not present for jsonrequest
* v0.8.0
* Add onload and onerror
* v0.7.0
* Goodbye CoffeeScript
* v0.6.0
* Add jsonrequest plugin
* Add header() to Request and Response objects
* More tests
* v0.5.3
* Improve content-type matching
* v0.5.1
* Fix bug with non-404s being suppressed by errorOn404
* v0.5.0
* Return request object from http methods
* v0.4.0
* Added errorOn404 option
* Make defaults a method
* Make plugins` a method
* v0.3.0
* Response-like errors
* More tests
* v0.2.0
* Initial release as "httpplease"

[promises plugin]: https://github.com/matthewwithanm/httpplease-promises
[browserify]: http://browserify.org
[webpack]: http://webpack.github.io
[Bower]: http://bower.io
[driverdan]: https://github.com/driverdan
[node-XMLHttpRequest]: https://github.com/driverdan/node-XMLHttpRequest
[xhr]: https://github.com/Raynos/xhr
[httpify]: https://github.com/scottcorgan/httpify
[request]: https://github.com/mikeal/request
[commit log]: https://github.com/matthewwithanm/httpplease.js/commits/master