Skip to content

HTTPS clone URL

Subversion checkout URL

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