Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 126 lines (84 sloc) 4.009 kb
f808b57 TJ Holowaychuk Initial commit
tj authored
1
aa6acd6 TJ Holowaychuk Added the start of markdown docs
tj authored
2 # SuperAgent
f808b57 TJ Holowaychuk Initial commit
tj authored
3
b0d8b35 TJ Holowaychuk 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 Holowaychuk Initial commit
tj authored
5
f310123 TJ Holowaychuk the new face of superagent
tj authored
6 ![super agent](http://f.cl.ly/items/3d282n3A0h0Z0K2w0q2a/Screenshot.png)
7
f808b57 TJ Holowaychuk 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 Holowaychuk docs
tj authored
58 .set('Accept', 'application/json')
f808b57 TJ Holowaychuk 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
83 ## Running tests
84
85 Install the test server deps (nodejs / express):
86
87 $ npm install -d
88
89 Start the test server:
90
760e767 TJ Holowaychuk setting up mocha tests
tj authored
91 $ make test-server
f808b57 TJ Holowaychuk Initial commit
tj authored
92
32a569b TJ Holowaychuk redirect / -> /test/
tj authored
93 Visit `localhost:3000/` in the browser.
f808b57 TJ Holowaychuk Initial commit
tj authored
94
95 ## Browser support
96
aa6acd6 TJ Holowaychuk Added the start of markdown docs
tj authored
97 Actively tested with:
f808b57 TJ Holowaychuk Initial commit
tj authored
98
99 - Firefox 5.x
100 - Safari 5.x
101 - Chrome 13.x
102
103 ## License
104
105 (The MIT License)
106
107 Copyright (c) 2011 TJ Holowaychuk <tj@vision-media.ca>
108
109 Permission is hereby granted, free of charge, to any person obtaining
110 a copy of this software and associated documentation files (the
111 'Software'), to deal in the Software without restriction, including
112 without limitation the rights to use, copy, modify, merge, publish,
113 distribute, sublicense, and/or sell copies of the Software, and to
114 permit persons to whom the Software is furnished to do so, subject to
115 the following conditions:
116
117 The above copyright notice and this permission notice shall be
118 included in all copies or substantial portions of the Software.
119
120 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
121 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
122 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
123 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
124 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
125 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
126 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.