Package Exports

httpplease
httpplease/lib/createxhr-browser.js
httpplease/lib/createxhr.js
httpplease/lib/plugins/oldiexdomain

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (httpplease) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

browserify and webpack users can simply npm install httpplease.

<script> tag fans can grab the standalone build from the "browser-builds" directory.

Minified and gzipped, the standalone browser build is <2K.

API

Making a request

httpplease.get('http://example.com', function(err, res) {
    // Do something with the result.
});

Alternatively, you can pass a request 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.
});

The request object

The request object supports the following properties:

Name	Description
`url`	The URL to request.
`method`	The HTTP method to use for the request.
`body`	The body to send with the request.
`headers`	An object containing HTTP headers to send, for example: `{Accept: '/'}`.

The response object

The response object passed to your callback in the event of a successful request has the following properties:

`status`	The numeric status code.
`text`	The raw response text.
`body`	The processed response body. Depending on the content type of the response and the plugins being used, this may be the same as `response.text` (a string) or some other object (like a parsed JSON object).
`contentType`	The content type of the response.
`headers`	An object containing the parsed response headers.
`request`	An object representing the request.
`xhr`	The XHR or XDomain object used to make the request.

The error object

In the event of an error, an error object will be passed as the first argument to your callback. It has the following properties:

`status`	The numeric status code.
`message`	A description of the error.
`request`	An object representing the request.
`xhr`	The XHR or XDomain object used to make the request.

Plugins

httpplease supports plugins for changing how requests are made. Some plugins are built in:

Name	Enabled by Default?	Description
jsonparser	No	Converts JSON responses into JS objects on `response.body`.
cleanurl	Yes	Encodes unencoded characters in the request URL. Required by some browsers if you're using non-ASCII characters.
oldiexdomain	No	Enables cross domain requests in IE9 by (transparently) using the `XDomainRequest` object when necessary.
oldieactivex	No	For super old versions of IE that didn't define XMLHttpRequest, use an ActiveX object.

Plugins are enabled with the use method:

var jsonparser = require('httpplease/lib/plugins/jsonparser');
httpplease = httpplease.use(jsonparser);

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 jsonparser = httppleaseplugins.jsonparser;
httpplease = httpplease.use(jsonparser);

Notice that use returns a new httpplease instance. This is so that you can create multiple instances, each with their own plugins:

var request = httpplease.use(jsonparser);

request
  .use(oldiexdomain)
  .get('http://example.com', function(err, res) { ... }); // Uses "jsonparser" plugin and "oldiexdomain".
request.get('http://example.com', function(err, res) { ... }); // Only uses "jsonparser" 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 request = httpplease
  .use(jsonparser, 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 request = 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:

Method	Description
`createXHR(req)`	Creates an XHR object. The first plugin that return a non-null value from this method will be used.
`processRequest(req)`	This method gives the plugin a chance to manipulate the request object before the request is made. For example, it can change the body or add headers.
`processResponse(res)`	This method gives the plugin a chance to manipulate the response object before the callback is invoked.

Similar Projects

xhr (browser only)
httpify (wraps xhr and request)