mirror of
https://github.com/wahyd4/cdnjs.git
synced 2026-08-12 06:16:02 +10:00
220 lines
6.7 KiB
Markdown
220 lines
6.7 KiB
Markdown
# SuperAgent
|
|
|
|
Super Agent is light-weight progressive ajax API crafted for flexibility, readability, and a low learning curve after being frustrated with many of the existing request APIs.
|
|
|
|
request
|
|
.post('/api/pet')
|
|
.send({ name: 'Manny', species: 'cat' })
|
|
.set('X-API-Key', 'foobar')
|
|
.set('Accept', 'application/json')
|
|
.end(function(res){
|
|
if (res.ok) {
|
|
alert('yay got ' + JSON.stringify(res.body));
|
|
} else {
|
|
alert('Oh no! error ' + res.text);
|
|
}
|
|
});
|
|
|
|
## Request basics
|
|
|
|
A request can be initiated by invoking the appropriate method on the `request` object, then calling `.end()` to send the request. For example a simple GET request:
|
|
|
|
request
|
|
.get('/search')
|
|
.end(function(res){
|
|
|
|
});
|
|
|
|
The __node__ client may also provide absolute urls:
|
|
|
|
request
|
|
.get('http://example.com/search')
|
|
.end(function(res){
|
|
|
|
});
|
|
|
|
__DELETE__, __HEAD__, __POST__, __PUT__ and other __HTTP__ verbs may also be used, simply change the method name:
|
|
|
|
request
|
|
.head('/favicon.ico')
|
|
.end(function(res){
|
|
|
|
});
|
|
|
|
__DELETE__ is a special-case, as it's a reserved word, so the method is named `.del()`:
|
|
|
|
request
|
|
.del('/user/1')
|
|
.end(function(res){
|
|
|
|
});
|
|
|
|
### Crafting requests
|
|
|
|
SuperAgent's flexible API gives you the granularity you need, _when_ you need, yet more concise variations help reduce the amount of code necessary. For example the following GET request:
|
|
|
|
request
|
|
.get('/search')
|
|
.end(function(res){
|
|
|
|
});
|
|
|
|
Could also be defined as the following, where a callback is given to the HTTP verb method:
|
|
|
|
request
|
|
.get('/search', function(res){
|
|
|
|
});
|
|
|
|
Taking this further the default HTTP verb is __GET__ so the following works as well:
|
|
|
|
request('/search', function(res){
|
|
|
|
});
|
|
|
|
This applies to more complicated requests as well, for example the following __GET__ request with a query-string can be written in the chaining manner:
|
|
|
|
request
|
|
.get('/search')
|
|
.send({ query: 'tobi the ferret' })
|
|
.end(function(res){
|
|
|
|
});
|
|
|
|
Or one may pass the query-string object to `.get()`:
|
|
|
|
request
|
|
.get('/search', { query: 'tobi the ferret' })
|
|
.end(function(res){
|
|
|
|
});
|
|
|
|
Taking this even further the callback may be passed as well:
|
|
|
|
request
|
|
.get('/search', { query: 'tobi the ferret' }, function(res){
|
|
|
|
});
|
|
|
|
## Dealing with errors
|
|
|
|
On a network error (e.g. connection refused or timeout), SuperAgent emits
|
|
`error` unless you pass `.end()` a callback with two parameters. Then
|
|
SuperAgent will invoke it with the error first, followed by a null response.
|
|
|
|
request
|
|
.get('http://wrongurl')
|
|
.end(function(err, res){
|
|
console.log('ERROR: ', err)
|
|
});
|
|
|
|
On HTTP errors instead, SuperAgent populates the response with flags
|
|
indicating the error. See `Response status` below.
|
|
|
|
## Setting header fields
|
|
|
|
Setting header fields is simple, invoke `.set()` with a field name and value:
|
|
|
|
request
|
|
.get('/search')
|
|
.set('API-Key', 'foobar')
|
|
.set('Accept', 'application/json')
|
|
.end(callback);
|
|
|
|
## GET requests
|
|
|
|
The `.send()` method accepts objects, which when used with the __GET__ method will form a query-string. The following will produce the path `/search?query=Manny&range=1..5&order=desc`.
|
|
|
|
request
|
|
.get('/search')
|
|
.send({ query: 'Manny' })
|
|
.send({ range: '1..5' })
|
|
.send({ order: 'desc' })
|
|
.end(function(res){
|
|
|
|
});
|
|
|
|
The `.send()` method accepts strings as well:
|
|
|
|
request
|
|
.get('/querystring')
|
|
.send('search=Manny&range=1..5')
|
|
.end(function(res){
|
|
|
|
});
|
|
|
|
### POST / PUT requests
|
|
|
|
A typical JSON __POST__ request might look a little like the following, where we set the Content-Type header field appropriately, and "write" some data, in this case just a JSON string.
|
|
|
|
request.post('/user')
|
|
.set('Content-Type', 'application/json')
|
|
.send('{"name":"tj","pet":"tobi"})
|
|
.end(callback)
|
|
|
|
Since JSON is undoubtably the most common, it's the _default_! The following example is equivalent to the previous.
|
|
|
|
request.post('/user')
|
|
.send({ name: 'tj', pet: 'tobi' })
|
|
.end(callback)
|
|
|
|
Or using multiple `.send()` calls:
|
|
|
|
request.post('/user')
|
|
.send({ name: 'tj' })
|
|
.send({ pet: 'tobi' })
|
|
.end(callback)
|
|
|
|
SuperAgent formats are extensible, however by default "json" and "form" are supported. To send the data as `application/x-www-form-urlencoded` simply invoke `.type()` with "form-data", where the default is "json". This request will POST the body "name=tj&pet=tobi".
|
|
|
|
request.post('/user')
|
|
.type('form')
|
|
.send({ name: 'tj' })
|
|
.send({ pet: 'tobi' })
|
|
.end(callback)
|
|
|
|
## Response properties
|
|
|
|
Many helpful flags and properties are set on the `Response` object, ranging from the response text, parsed response body, header fields, status flags and more.
|
|
|
|
### Response text
|
|
|
|
The `res.text` property contains the unparsed response body string.
|
|
|
|
### Response body
|
|
|
|
Much like SuperAgent can auto-serialize request data, it can also automatically parse it. When a parser is defined for the Content-Type, it is parsed, which by default includes "application/json" and "application/x-www-form-urlencoded". The parsed object is then available via `res.body`.
|
|
|
|
### Response header fields
|
|
|
|
The `res.header` contains an object of parsed header fields, lowercasing field names much like node does. For example `res.header['content-length']`.
|
|
|
|
### Response Content-Type
|
|
|
|
The Content-Type response header is special-cased, providing `res.contentType`, which is void of the charset (if any). For example the Content-Type of "text/html; charset=utf8" will provide "text/html" as `res.contentType`, and the `res.charset` property would then contain "utf8".
|
|
|
|
### Response status
|
|
|
|
The response status flags help determine if the request was a success, among other useful information, making SuperAgent ideal for interacting with RESTful web services. These flags are currently defined as:
|
|
|
|
var type = status / 100 | 0;
|
|
|
|
// status / class
|
|
res.status = status;
|
|
res.statusType = type;
|
|
|
|
// basics
|
|
res.info = 1 == type;
|
|
res.ok = 2 == type;
|
|
res.clientError = 4 == type;
|
|
res.serverError = 5 == type;
|
|
res.error = 4 == type || 5 == type;
|
|
|
|
// sugar
|
|
res.accepted = 202 == status;
|
|
res.noContent = 204 == status || 1223 == status;
|
|
res.badRequest = 400 == status;
|
|
res.unauthorized = 401 == status;
|
|
res.notAcceptable = 406 == status;
|
|
res.notFound = 404 == status;
|