Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 125 lines (81 sloc) 3.881 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
6732a11 @tj docs
tj authored
8 ## Motivation
f808b57 @tj Initial commit
tj authored
9
6732a11 @tj docs
tj authored
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!
f808b57 @tj Initial commit
tj authored
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
ff681cc @tj docs
tj authored
51 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:
f808b57 @tj Initial commit
tj authored
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 building on the existing API internally we also provide something similar to `$.post()` for those times in life where your interactions are very basic:
65
66 ```js
67 request.post('/api/pet', cat, function(res){
68
69 });
70 ```
71
8e52028 @tj make test docs
tj authored
72 ## Running node tests
73
74 Install dependencies:
75
76 $ npm install -d
77
78 Run em!
79
80 $ make test
81
82 ## Running browser tests
f808b57 @tj Initial commit
tj authored
83
84 Install the test server deps (nodejs / express):
85
86 $ npm install -d
87
88 Start the test server:
89
760e767 @tj setting up mocha tests
tj authored
90 $ make test-server
f808b57 @tj Initial commit
tj authored
91
32a569b @tj redirect / -> /test/
tj authored
92 Visit `localhost:3000/` in the browser.
f808b57 @tj Initial commit
tj authored
93
94 ## Browser support
95
aa6acd6 @tj Added the start of markdown docs
tj authored
96 Actively tested with:
f808b57 @tj Initial commit
tj authored
97
98 - Firefox 5.x
99 - Safari 5.x
100 - Chrome 13.x
101
102 ## License
103
104 (The MIT License)
105
106 Copyright (c) 2011 TJ Holowaychuk <tj@vision-media.ca>
107
108 Permission is hereby granted, free of charge, to any person obtaining
109 a copy of this software and associated documentation files (the
110 'Software'), to deal in the Software without restriction, including
111 without limitation the rights to use, copy, modify, merge, publish,
112 distribute, sublicense, and/or sell copies of the Software, and to
113 permit persons to whom the Software is furnished to do so, subject to
114 the following conditions:
115
116 The above copyright notice and this permission notice shall be
117 included in all copies or substantial portions of the Software.
118
119 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
120 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
121 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
122 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
123 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
124 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
125 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.