Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Ajax with less suck - (and node.js HTTP client to match)

Merge pull request #567 from rase-/update/only-add-xhr-progress-liste…

…ner-if-registered-on-request

Add xhr upload listener only if present on the request

Readme.md

SuperAgent Build Status

Sauce Test Status

SuperAgent is a small progressive client-side HTTP request library, and Node.js module with the same API, sporting many high-level HTTP client features. View the docs.

super agent

Installation

node:

$ npm install superagent

component:

$ component install visionmedia/superagent

with script tags use ./superagent.js

Motivation

This library spawned from my frustration with jQuery's weak & inconsistent Ajax support. jQuery's API, while having recently added some promise-like support, is largely static, forcing you to build up big objects containing all the header fields and options, not to mention most of the options are awkwardly named "type" instead of "method", etc. Onto examples!

The following is what you might typically do for a simple GET with jQuery:

$.get('/user/1', function(data, textStatus, xhr){

});

Great, it's ok, but it's kinda lame having 3 arguments just to access something on the xhr. Our equivalent would be:

request.get('/user/1', function(res){

});

The response object is an instanceof request.Response, encapsulating all of this information instead of throwing a bunch of arguments at you. For example, we can check res.status, res.header for header fields, res.text, res.body etc.

An example of a JSON POST with jQuery typically might use $.post(), however once you need to start defining header fields you have to then re-write it using $.ajax()... so that might look like:

$.ajax({
  url: '/api/pet',
  type: 'POST',
  data: { name: 'Manny', species: 'cat' },
  headers: { 'X-API-Key': 'foobar' }
}).success(function(res){

}).error(function(){

});

Not only is it ugly, but it's pretty opinionated. jQuery likes to special-case {4,5}xx- for example, you cannot (easily at least) receive a parsed JSON response for say "400 Bad Request". This same request would look like this:

request
  .post('/api/pet')
  .send({ name: 'Manny', species: 'cat' })
  .set('X-API-Key', 'foobar')
  .set('Accept', 'application/json')
  .end(function(error, res){

  });

Supported browsers

Tested browsers:

  • Latest Android
  • Latest Firefox
  • Latest Chrome
  • IE9 through latest
  • Latest iPhone
  • Latest Safari

Even though IE9 is supported, a polyfill window.btoa is needed to use basic auth.

Plugins

Usage:

var nocache = require('no-cache');
var request = require('superagent');
var prefix = require('superagent-prefix')('/static');

prefix(request); // Prefixes *all* requests

request
.get('/some-url')
.use(nocache) // Prevents caching of *only* this request
.end(function(res){
    // Do something
});

Existing plugins:

Please prefix your plugin component with superagent-*

For superagent extensions such as couchdb and oauth visit the wiki.

Running node tests

Install dependencies:

 $ npm install

Run em!

$ make test

Running browser tests

Install dependencies:

$ npm install

Start the test runner:

$ make test-browser-local

Visit http://localhost:4000/__zuul in your browser.

Edit tests and refresh your browser. You do not have to restart the test runner.

Browser build

The browser build of superagent is located in ./superagent.js

Examples:

License

MIT

Something went wrong with that request. Please try again.