1 | # SuperAgent [![Build Status](https://travis-ci.org/visionmedia/superagent.svg?branch=master)](https://travis-ci.org/visionmedia/superagent)
|
2 |
|
3 | [![Sauce Test Status](https://saucelabs.com/browser-matrix/shtylman-superagent.svg)](https://saucelabs.com/u/shtylman-superagent)
|
4 |
|
5 | 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](http://visionmedia.github.io/superagent/).
|
6 |
|
7 | ![super agent](http://f.cl.ly/items/3d282n3A0h0Z0K2w0q2a/Screenshot.png)
|
8 |
|
9 | ## Installation
|
10 |
|
11 | node:
|
12 |
|
13 | ```
|
14 | $ npm install superagent
|
15 | ```
|
16 |
|
17 | Works with [browserify](https://github.com/substack/node-browserify) and should work with [webpack](https://github.com/visionmedia/superagent/wiki/SuperAgent-for-Webpack)
|
18 |
|
19 | ```js
|
20 | request
|
21 | .post('/api/pet')
|
22 | .send({ name: 'Manny', species: 'cat' })
|
23 | .set('X-API-Key', 'foobar')
|
24 | .set('Accept', 'application/json')
|
25 | .end(function(err, res){
|
26 | // Calling the end function will send the request
|
27 | });
|
28 | ```
|
29 |
|
30 | ## Supported browsers and Node versions
|
31 |
|
32 | Tested browsers:
|
33 |
|
34 | - Latest Firefox, Chrome, Safari
|
35 | - Latest Android, iPhone
|
36 | - IE10 through latest. IE9 with polyfills.
|
37 |
|
38 | Even though IE9 is supported, a polyfill for `window.FormData` is required for `.field()`.
|
39 |
|
40 | Node 4 or later is required.
|
41 |
|
42 | # Plugins
|
43 |
|
44 | SuperAgent is easily extended via plugins.
|
45 |
|
46 | ```js
|
47 | var nocache = require('superagent-no-cache');
|
48 | var request = require('superagent');
|
49 | var prefix = require('superagent-prefix')('/static');
|
50 |
|
51 | request
|
52 | .get('/some-url')
|
53 | .query({ action: 'edit', city: 'London' }) // query string
|
54 | .use(prefix) // Prefixes *only* this request
|
55 | .use(nocache) // Prevents caching of *only* this request
|
56 | .end(function(err, res){
|
57 | // Do something
|
58 | });
|
59 | ```
|
60 |
|
61 | Existing plugins:
|
62 | * [superagent-no-cache](https://github.com/johntron/superagent-no-cache) - prevents caching by including Cache-Control header
|
63 | * [superagent-prefix](https://github.com/johntron/superagent-prefix) - prefixes absolute URLs (useful in test environment)
|
64 | * [superagent-suffix](https://github.com/timneutkens1/superagent-suffix) - suffix URLs with a given path
|
65 | * [superagent-mock](https://github.com/M6Web/superagent-mock) - simulate HTTP calls by returning data fixtures based on the requested URL
|
66 | * [superagent-mocker](https://github.com/shuvalov-anton/superagent-mocker) — simulate REST API
|
67 | * [superagent-cache](https://github.com/jpodwys/superagent-cache) - A global SuperAgent patch with built-in, flexible caching (compatible with SuperAgent `1.x`)
|
68 | * [superagent-cache-plugin](https://github.com/jpodwys/superagent-cache-plugin) - A SuperAgent plugin with built-in, flexible caching (compatible with SuperAgent `1.x`)
|
69 | * [superagent-jsonapify](https://github.com/alex94puchades/superagent-jsonapify) - A lightweight [json-api](http://jsonapi.org/format/) client addon for superagent
|
70 | * [superagent-serializer](https://github.com/zzarcon/superagent-serializer) - Converts server payload into different cases
|
71 | * [superagent-use](https://github.com/koenpunt/superagent-use) - A client addon to apply plugins to all requests.
|
72 | * [superagent-httpbackend](https://www.npmjs.com/package/superagent-httpbackend) - stub out requests using AngularJS' $httpBackend syntax
|
73 | * [superagent-throttle](https://github.com/leviwheatcroft/superagent-throttle) - queues and intelligently throttles requests
|
74 | * [superagent-charset](https://github.com/magicdawn/superagent-charset) - add charset support for node's SuperAgent
|
75 |
|
76 | Please prefix your plugin with `superagent-*` so that it can easily be found by others.
|
77 |
|
78 | For SuperAgent extensions such as couchdb and oauth visit the [wiki](https://github.com/visionmedia/superagent/wiki).
|
79 |
|
80 | ## Running node tests
|
81 |
|
82 | Install dependencies:
|
83 |
|
84 | ```shell
|
85 | $ npm install
|
86 | ```
|
87 | Run em!
|
88 |
|
89 | ```shell
|
90 | $ make test
|
91 | ```
|
92 |
|
93 | ## Running browser tests
|
94 |
|
95 | Install dependencies:
|
96 |
|
97 | ```shell
|
98 | $ npm install
|
99 | ```
|
100 |
|
101 | Start the test runner:
|
102 |
|
103 | ```shell
|
104 | $ make test-browser-local
|
105 | ```
|
106 |
|
107 | Visit `http://localhost:4000/__zuul` in your browser.
|
108 |
|
109 | Edit tests and refresh your browser. You do not have to restart the test runner.
|
110 |
|
111 |
|
112 | ## Packaging Notes for Developers
|
113 |
|
114 | **npm (for node)** is configured via the `package.json` file and the `.npmignore` file. Key metadata in the `package.json` file is the `version` field which should be changed according to semantic versioning and have a 1-1 correspondence with git tags. So for example, if you were to `git show v1.5.0:package.json | grep version`, you should see `"version": "1.5.0",` and this should hold true for every release. This can be handled via the `npm version` command. Be aware that when publishing, npm will presume the version being published should also be tagged in npm as `latest`, which is OK for normal incremental releases. For betas and minor/patch releases to older versions, be sure to include `--tag` appropriately to avoid an older release getting tagged as `latest`.
|
115 |
|
116 | **npm (for browser standalone)** When we publish versions to npm, we run `make superagent.js` which generates the standalone `superagent.js` file via `browserify`, and this file is included in the package published to npm (but this file is never checked into the git repository). If users want to install via npm but serve a single `.js` file directly to the browser, the `node_modules/superagent/superagent.js` is a standalone browserified file ready to go for that purpose. It is not minified.
|
117 |
|
118 | **npm (for browserify)** is handled via the `package.json` `browser` field which allows users to install SuperAgent via npm, reference it from their browser code with `require('superagent')`, and then build their own application bundle via `browserify`, which will use `lib/client.js` as the SuperAgent entrypoint.
|
119 |
|
120 | **bower** is configured via the `bower.json` file. Bower installs files directly from git/github without any transformation, so you *must* use Browserify or Webpack (or use npm).
|
121 |
|
122 | ## License
|
123 |
|
124 | MIT
|