Skip to content

HTTPS clone URL

Subversion checkout URL

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