superagent

What is superagent?

The superagent npm package is a small progressive client-side HTTP request library, and Node.js module with the same API, sporting many high-level HTTP client features. It is designed to make HTTP requests from both Node.js and browsers.

What are superagent's main functionalities?

GET requests

This feature allows you to make GET requests to retrieve data from a server. You can include query parameters and handle the response asynchronously.

superagent.get('/search').query({ query: 'Manny' }).end(function(err, res){ /* handling response */ });

POST requests

This feature is used to send POST requests to a server. You can send data as part of the request body and set custom headers.

superagent.post('/api/pets').send({ name: 'Manny', species: 'cat' }).set('X-API-Key', 'foobar').end(function(err, res){ /* handling response */ });

Handling responses

This feature allows you to handle responses from the server, checking if the request was successful and then acting on the data received.

superagent.get('/some-url').end(function(err, res){ if (res.ok) { console.log('yay got ' + JSON.stringify(res.body)); } else { console.log('Oh no! error ' + res.text); } });

Promises and async/await

Superagent can be used with promises and async/await syntax for better asynchronous control flow.

async function getData() { try { const res = await superagent.get('/some-url'); console.log(res.body); } catch (err) { console.error(err); } }

Pipelining requests

This feature allows you to pipe the response stream directly to a file or another writable stream.

superagent.get('/some-url').pipe(fs.createWriteStream('result.txt'))

Other packages similar to superagent

axios

Axios is a promise-based HTTP client for the browser and Node.js. It provides a simple API and handles requests and responses in JSON format. Compared to superagent, it has built-in CSRF protection and supports interceptors for request and response transformation.

fetch

The Fetch API provides a more modern alternative to XMLHttpRequest for making HTTP requests in the browser. It is not an npm package but a built-in browser API. It returns promises and works with async/await. Unlike superagent, it is not Node.js compatible without polyfills.

got

Got is a Node.js HTTP request library that is designed to be a simpler and more user-friendly alternative to Node's native 'http' module. It supports promises and async/await, streams, and advanced features like retries and timeouts. It is often compared to superagent for its simplicity and feature set.

node-fetch

node-fetch is a light-weight module that brings the browser Fetch API to Node.js. It is similar to superagent but is designed to mimic the Fetch API as closely as possible. It is promise-based and supports stream consumption.

request

Request is a simplified HTTP request client for Node.js, but it has been deprecated. It was known for its simplicity and wide adoption. Superagent offers a similar feature set but continues to be maintained and updated.

README

SuperAgent

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.

Installation

node:

$ npm install superagent

component:

$ component install visionmedia/superagent

Works with browserify and should work with webpack

request
  .post('/api/pet')
  .send({ name: 'Manny', species: 'cat' })
  .set('X-API-Key', 'foobar')
  .set('Accept', 'application/json')
  .end(function(err, 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

Superagent is easily extended via plugins.

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:

• superagent-no-cache - prevents caching by including Cache-Control header
• superagent-prefix - prefixes absolute URLs (useful in test environment)

Please prefix your plugin with superagent-* so that it can easily be found by others.

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.

License

MIT

Changelog

1.0.0 / 2015-03-08

• All non-200 responses are treated as errors now. (The callback is called with an error when the response has a status < 200 or >= 300 now. In previous versions this would not have raised an error and the client would have to check the res object. See #283.
• keep timeouts intact across redirects (hopkinsth)
• handle falsy json values (themaarten)
• fire response events in browser version (Schoonology)
• getXHR exported in client version (KidsKilla)
• remove arity check on .end() callbacks (defunctzombie)
• avoid setting content-type for host objects (rexxars)
• don't index array strings in querystring (travisjeffery)
• fix pipe() with redirects (cyrilis)
• add xhr2 file download (vstirbu)
• set default response type to text/plain if not specified (warrenseine)