Skip to content
This repository
Newer
Older
100644 130 lines (86 sloc) 4.011 kb
f808b57d »
2011-08-05 Initial commit
1
aa6acd64 »
2011-09-20 Added the start of markdown docs
2 # SuperAgent
f808b57d »
2011-08-05 Initial commit
3
aa6acd64 »
2011-09-20 Added the start of markdown docs
4 SuperAgent is an elegant, small (~1.7kb compressed), progressive client-side HTTP request library.
f808b57d »
2011-08-05 Initial commit
5
f3101234 »
2011-08-18 the new face of superagent
6 ![super agent](http://f.cl.ly/items/3d282n3A0h0Z0K2w0q2a/Screenshot.png)
7
a19c0d46 »
2011-08-05 docs link
8 ## Links
9
10 - API [docs](http://visionmedia.github.com/superagent/)
11
f808b57d »
2011-08-05 Initial commit
12 ## About
13
14 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!
15
16 Before we get started, superagent is namespaced to `superagent`, however I personally like to just call this `request`:
17
18 ```js
19 request = superagent;
20 ```
21
22 The following is what you might typically do for a simple __GET__ with jQuery:
23
24 ```js
25 $.get('/user/1', function(data, textStatus, xhr){
26
27 });
28 ```
29
30 great, it's ok, but it's kinda lame having 3 arguments just to access something on the `xhr`. Our equivalent would be:
31
32 ```js
33 request.get('/user/1', function(res){
34
35 });
36 ```
37
38 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.
39
40 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:
41
42 ```js
43 $.ajax({
44 url: '/api/pet',
45 type: 'POST',
46 data: { name: 'Manny', species: 'cat' },
47 headers: { 'X-API-Key': 'foobar' }
48 }).success(function(res){
49
50 }).error(function(){
51
52 });
53 ```
54
55 Not only is it ugly, it's opinionated, jQuery likes to treat {4,5}xx responses specifically, for example you cannot (easily at least) receive a parsed JSON response for say "400 Bad Request". This same request would look like this:
56
57 ```js
58 request
59 .post('/api/pet')
60 .data({ name: 'Manny', species: 'cat' })
61 .set('X-API-Key', 'foobar')
d2c189ff »
2011-08-05 docs
62 .set('Accept', 'application/json')
f808b57d »
2011-08-05 Initial commit
63 .end(function(res){
64
65 });
66 ```
67
68 or we can pass data to `.send()` which combines `.data()` and `.end()`, which is really ugly unless you are passing a variable:
69
70 ```js
71 request
72 .post('/api/pet')
73 .set('X-API-Key', 'foobar')
74 .send(cat, function(res){
75
76 });
77 ```
78
79 building on the existing API internally we also provide something similar to `$.post()` for those times in life where your interactions are very basic:
80
81 ```js
82 request.post('/api/pet', cat, function(res){
83
84 });
85 ```
86
87 ## Running tests
88
89 Install the test server deps (nodejs / express):
90
91 $ npm install -d
92
93 Start the test server:
94
95 $ make test
96
32a569ba »
2011-09-08 redirect / -> /test/
97 Visit `localhost:3000/` in the browser.
f808b57d »
2011-08-05 Initial commit
98
99 ## Browser support
100
aa6acd64 »
2011-09-20 Added the start of markdown docs
101 Actively tested with:
f808b57d »
2011-08-05 Initial commit
102
103 - Firefox 5.x
104 - Safari 5.x
105 - Chrome 13.x
106
107 ## License
108
109 (The MIT License)
110
111 Copyright (c) 2011 TJ Holowaychuk <tj@vision-media.ca>
112
113 Permission is hereby granted, free of charge, to any person obtaining
114 a copy of this software and associated documentation files (the
115 'Software'), to deal in the Software without restriction, including
116 without limitation the rights to use, copy, modify, merge, publish,
117 distribute, sublicense, and/or sell copies of the Software, and to
118 permit persons to whom the Software is furnished to do so, subject to
119 the following conditions:
120
121 The above copyright notice and this permission notice shall be
122 included in all copies or substantial portions of the Software.
123
124 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
125 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
126 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
127 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
128 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
129 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
130 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.