Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 125 lines (81 sloc) 3.935 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
6dcc9b2 TJ Holowaychuk docs
tj authored
4 SuperAgent is a small progressive client-side HTTP request library, and Node.js module with the same API, sporting many high-level HTTP client features. 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
6732a11 TJ Holowaychuk docs
tj authored
8 ## Motivation
f808b57 TJ Holowaychuk Initial commit
tj authored
9
6732a11 TJ Holowaychuk 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 Holowaychuk 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 Holowaychuk 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 Holowaychuk Initial commit
tj authored
52
53 ```js
54 request
55 .post('/api/pet')
6dcc9b2 TJ Holowaychuk docs
tj authored
56 .send({ name: 'Manny', species: 'cat' })
f808b57 TJ Holowaychuk Initial commit
tj authored
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 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 Holowaychuk 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 Holowaychuk 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 Holowaychuk setting up mocha tests
tj authored
90 $ make test-server
f808b57 TJ Holowaychuk Initial commit
tj authored
91
32a569b TJ Holowaychuk redirect / -> /test/
tj authored
92 Visit `localhost:3000/` in the browser.
f808b57 TJ Holowaychuk Initial commit
tj authored
93
94 ## Browser support
95
aa6acd6 TJ Holowaychuk Added the start of markdown docs
tj authored
96 Actively tested with:
f808b57 TJ Holowaychuk 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.