Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 132 lines (89 sloc) 4.35 kb
aa6acd6 TJ Holowaychuk Added the start of markdown docs
tj authored
1 # SuperAgent
f808b57 TJ Holowaychuk Initial commit
tj authored
2
3518302 TJ Holowaychuk Update Readme.md
tj authored
3 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
4
f310123 TJ Holowaychuk the new face of superagent
tj authored
5 ![super agent](http://f.cl.ly/items/3d282n3A0h0Z0K2w0q2a/Screenshot.png)
6
6732a11 TJ Holowaychuk docs
tj authored
7 ## Motivation
f808b57 TJ Holowaychuk Initial commit
tj authored
8
6732a11 TJ Holowaychuk docs
tj authored
9 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
10
11 The following is what you might typically do for a simple __GET__ with jQuery:
12
13 ```js
14 $.get('/user/1', function(data, textStatus, xhr){
49fc643 Hunter Loftis updated readme with agent usage
hunterloftis authored
15
f808b57 TJ Holowaychuk Initial commit
tj authored
16 });
17 ```
18
19 great, it's ok, but it's kinda lame having 3 arguments just to access something on the `xhr`. Our equivalent would be:
20
21 ```js
22 request.get('/user/1', function(res){
49fc643 Hunter Loftis updated readme with agent usage
hunterloftis authored
23
f808b57 TJ Holowaychuk Initial commit
tj authored
24 });
25 ```
26
27 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.
28
29 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:
30
31 ```js
32 $.ajax({
33 url: '/api/pet',
34 type: 'POST',
35 data: { name: 'Manny', species: 'cat' },
36 headers: { 'X-API-Key': 'foobar' }
37 }).success(function(res){
49fc643 Hunter Loftis updated readme with agent usage
hunterloftis authored
38
f808b57 TJ Holowaychuk Initial commit
tj authored
39 }).error(function(){
49fc643 Hunter Loftis updated readme with agent usage
hunterloftis authored
40
f808b57 TJ Holowaychuk Initial commit
tj authored
41 });
42 ```
43
ff681cc TJ Holowaychuk docs
tj authored
44 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
45
46 ```js
47 request
48 .post('/api/pet')
6dcc9b2 TJ Holowaychuk docs
tj authored
49 .send({ name: 'Manny', species: 'cat' })
f808b57 TJ Holowaychuk Initial commit
tj authored
50 .set('X-API-Key', 'foobar')
d2c189f TJ Holowaychuk docs
tj authored
51 .set('Accept', 'application/json')
f808b57 TJ Holowaychuk Initial commit
tj authored
52 .end(function(res){
49fc643 Hunter Loftis updated readme with agent usage
hunterloftis authored
53
f808b57 TJ Holowaychuk Initial commit
tj authored
54 });
55 ```
56
57 building on the existing API internally we also provide something similar to `$.post()` for those times in life where your interactions are very basic:
58
59 ```js
60 request.post('/api/pet', cat, function(res){
49fc643 Hunter Loftis updated readme with agent usage
hunterloftis authored
61
f808b57 TJ Holowaychuk Initial commit
tj authored
62 });
63 ```
64
8e52028 TJ Holowaychuk make test docs
tj authored
65 ## Running node tests
66
67 Install dependencies:
49fc643 Hunter Loftis updated readme with agent usage
hunterloftis authored
68
8e52028 TJ Holowaychuk make test docs
tj authored
69 $ npm install -d
49fc643 Hunter Loftis updated readme with agent usage
hunterloftis authored
70
8e52028 TJ Holowaychuk make test docs
tj authored
71 Run em!
49fc643 Hunter Loftis updated readme with agent usage
hunterloftis authored
72
8e52028 TJ Holowaychuk make test docs
tj authored
73 $ make test
74
75 ## Running browser tests
f808b57 TJ Holowaychuk Initial commit
tj authored
76
77 Install the test server deps (nodejs / express):
78
79 $ npm install -d
80
81 Start the test server:
82
760e767 TJ Holowaychuk setting up mocha tests
tj authored
83 $ make test-server
f808b57 TJ Holowaychuk Initial commit
tj authored
84
32a569b TJ Holowaychuk redirect / -> /test/
tj authored
85 Visit `localhost:3000/` in the browser.
f808b57 TJ Holowaychuk Initial commit
tj authored
86
1d4146a Hunter Loftis updated readme with agent usage
hunterloftis authored
87 ## Persisting an agent (with cookies, ie sessions)
49fc643 Hunter Loftis updated readme with agent usage
hunterloftis authored
88
89 ```js
90 var request = require('superagent');
332489d Hunter Loftis updated example for clarity
hunterloftis authored
91 var user1 = request.agent();
92 user1
49fc643 Hunter Loftis updated readme with agent usage
hunterloftis authored
93 .post('http://localhost:4000/signin')
94 .send({ user: 'hunter@hunterloftis.com', password: 'password' })
95 .end(function(err, res) {
332489d Hunter Loftis updated example for clarity
hunterloftis authored
96 // user1 will manage its own cookies
97 // res.redirects contains an Array of redirects
49fc643 Hunter Loftis updated readme with agent usage
hunterloftis authored
98 });
99 ```
100
5f1ff17 Hunter Loftis added another example
hunterloftis authored
101 Examples:
102 - [agency tests](superagent/blob/master/test/node/agency.js)
103 - [express demo app](https://github.com/hunterloftis/component-test/blob/master/lib/users/test/controller.test.js)
49fc643 Hunter Loftis updated readme with agent usage
hunterloftis authored
104
b3240d9 TJ Holowaychuk wiki mention
tj authored
105 ## Wiki
106
107 For superagent extensions such as couchdb and oauth visit the [wiki](https://github.com/visionmedia/superagent/wiki).
108
49fc643 Hunter Loftis updated readme with agent usage
hunterloftis authored
109 ## License
f808b57 TJ Holowaychuk Initial commit
tj authored
110
111 (The MIT License)
112
113 Copyright (c) 2011 TJ Holowaychuk <tj@vision-media.ca>
114
115 Permission is hereby granted, free of charge, to any person obtaining
116 a copy of this software and associated documentation files (the
117 'Software'), to deal in the Software without restriction, including
118 without limitation the rights to use, copy, modify, merge, publish,
119 distribute, sublicense, and/or sell copies of the Software, and to
120 permit persons to whom the Software is furnished to do so, subject to
121 the following conditions:
122
123 The above copyright notice and this permission notice shall be
124 included in all copies or substantial portions of the Software.
125
126 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
127 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
128 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
129 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
130 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
131 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
132 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.