Skip to content
This repository
Newer
Older
100644 132 lines (89 sloc) 4.35 kb
aa6acd64 »
2011-09-20 Added the start of markdown docs
1 # SuperAgent
f808b57d »
2011-08-05 Initial commit
2
35183022 »
2012-05-19 Update Readme.md
3 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.com/superagent/).
f808b57d »
2011-08-05 Initial commit
4
f3101234 »
2011-08-18 the new face of superagent
5 ![super agent](http://f.cl.ly/items/3d282n3A0h0Z0K2w0q2a/Screenshot.png)
6
6732a11b »
2011-11-09 docs
7 ## Motivation
f808b57d »
2011-08-05 Initial commit
8
6732a11b »
2011-11-09 docs
9 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!
f808b57d »
2011-08-05 Initial commit
10
11 The following is what you might typically do for a simple __GET__ with jQuery:
12
13 ```js
14 $.get('/user/1', function(data, textStatus, xhr){
49fc6432 » hunterloftis
2012-08-08 updated readme with agent usage
15
f808b57d »
2011-08-05 Initial commit
16 });
17 ```
18
19 great, it's ok, but it's kinda lame having 3 arguments just to access something on the `xhr`. Our equivalent would be:
20
21 ```js
22 request.get('/user/1', function(res){
49fc6432 » hunterloftis
2012-08-08 updated readme with agent usage
23
f808b57d »
2011-08-05 Initial commit
24 });
25 ```
26
27 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.
28
29 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:
30
31 ```js
32 $.ajax({
33 url: '/api/pet',
34 type: 'POST',
35 data: { name: 'Manny', species: 'cat' },
36 headers: { 'X-API-Key': 'foobar' }
37 }).success(function(res){
49fc6432 » hunterloftis
2012-08-08 updated readme with agent usage
38
f808b57d »
2011-08-05 Initial commit
39 }).error(function(){
49fc6432 » hunterloftis
2012-08-08 updated readme with agent usage
40
f808b57d »
2011-08-05 Initial commit
41 });
42 ```
43
ff681ccf »
2011-11-09 docs
44 Not only is it ugly 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:
f808b57d »
2011-08-05 Initial commit
45
46 ```js
47 request
48 .post('/api/pet')
6dcc9b29 »
2012-01-24 docs
49 .send({ name: 'Manny', species: 'cat' })
f808b57d »
2011-08-05 Initial commit
50 .set('X-API-Key', 'foobar')
d2c189ff »
2011-08-05 docs
51 .set('Accept', 'application/json')
f808b57d »
2011-08-05 Initial commit
52 .end(function(res){
49fc6432 » hunterloftis
2012-08-08 updated readme with agent usage
53
f808b57d »
2011-08-05 Initial commit
54 });
55 ```
56
57 building on the existing API internally we also provide something similar to `$.post()` for those times in life where your interactions are very basic:
58
59 ```js
60 request.post('/api/pet', cat, function(res){
49fc6432 » hunterloftis
2012-08-08 updated readme with agent usage
61
f808b57d »
2011-08-05 Initial commit
62 });
63 ```
64
8e520288 »
2011-11-08 make test docs
65 ## Running node tests
66
67 Install dependencies:
49fc6432 » hunterloftis
2012-08-08 updated readme with agent usage
68
8e520288 »
2011-11-08 make test docs
69 $ npm install -d
49fc6432 » hunterloftis
2012-08-08 updated readme with agent usage
70
8e520288 »
2011-11-08 make test docs
71 Run em!
49fc6432 » hunterloftis
2012-08-08 updated readme with agent usage
72
8e520288 »
2011-11-08 make test docs
73 $ make test
74
75 ## Running browser tests
f808b57d »
2011-08-05 Initial commit
76
77 Install the test server deps (nodejs / express):
78
79 $ npm install -d
80
81 Start the test server:
82
760e767a »
2011-11-08 setting up mocha tests
83 $ make test-server
f808b57d »
2011-08-05 Initial commit
84
32a569ba »
2011-09-08 redirect / -> /test/
85 Visit `localhost:3000/` in the browser.
f808b57d »
2011-08-05 Initial commit
86
1d4146a6 » hunterloftis
2012-08-08 updated readme with agent usage
87 ## Persisting an agent (with cookies, ie sessions)
49fc6432 » hunterloftis
2012-08-08 updated readme with agent usage
88
89 ```js
90 var request = require('superagent');
332489d3 » hunterloftis
2012-08-08 updated example for clarity
91 var user1 = request.agent();
92 user1
49fc6432 » hunterloftis
2012-08-08 updated readme with agent usage
93 .post('http://localhost:4000/signin')
94 .send({ user: 'hunter@hunterloftis.com', password: 'password' })
95 .end(function(err, res) {
332489d3 » hunterloftis
2012-08-08 updated example for clarity
96 // user1 will manage its own cookies
97 // res.redirects contains an Array of redirects
49fc6432 » hunterloftis
2012-08-08 updated readme with agent usage
98 });
99 ```
100
5f1ff171 » hunterloftis
2012-08-08 added another example
101 Examples:
102 - [agency tests](superagent/blob/master/test/node/agency.js)
103 - [express demo app](https://github.com/hunterloftis/component-test/blob/master/lib/users/test/controller.test.js)
49fc6432 » hunterloftis
2012-08-08 updated readme with agent usage
104
b3240d9a »
2012-07-09 wiki mention
105 ## Wiki
106
107 For superagent extensions such as couchdb and oauth visit the [wiki](https://github.com/visionmedia/superagent/wiki).
108
49fc6432 » hunterloftis
2012-08-08 updated readme with agent usage
109 ## License
f808b57d »
2011-08-05 Initial commit
110
111 (The MIT License)
112
113 Copyright (c) 2011 TJ Holowaychuk <tj@vision-media.ca>
114
115 Permission is hereby granted, free of charge, to any person obtaining
116 a copy of this software and associated documentation files (the
117 'Software'), to deal in the Software without restriction, including
118 without limitation the rights to use, copy, modify, merge, publish,
119 distribute, sublicense, and/or sell copies of the Software, and to
120 permit persons to whom the Software is furnished to do so, subject to
121 the following conditions:
122
123 The above copyright notice and this permission notice shall be
124 included in all copies or substantial portions of the Software.
125
126 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
127 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
128 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
129 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
130 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
131 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
132 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.