superagent
Advanced tools
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.
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'))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.
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 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 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 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.
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.
node:
$ npm install superagent
component:
$ component install visionmedia/superagent
with script tags use ./superagent.js
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){
});
Building on the existing API internally, we also provide something similar to $.post() for those times in life where your interactions are very basic:
request.post('/api/pet', cat, function(error, res){
});
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.
Install dependencies:
$ npm install
Run em!
$ make test
Install the test server deps (nodejs / express):
$ npm install
Start the test server:
$ make test-server
Visit localhost:4000/ in the browser.
The browser build of superagent is located in ./superagent.js
MIT
0.18.1 / 2014-07-05
FAQs
elegant & feature rich browser / node HTTP with a fluent API
The npm package superagent receives a total of 7,988,433 weekly downloads. As such, superagent popularity was classified as popular.
We found that superagent demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.