Skip to content

Commit

Permalink
Add docs explaining how to add new default parsers/serializers.
Browse files Browse the repository at this point in the history
  • Loading branch information
shreyjain1994 authored and kornelski committed Jan 21, 2018
1 parent 2eed60f commit 276244c
Showing 1 changed file with 42 additions and 2 deletions.
44 changes: 42 additions & 2 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -208,8 +208,28 @@ simply the extension name such as "xml", "json", "png", etc:

## Serializing request body

SuperAgent will automatically serialize JSON and forms. If you want to send the payload in a custom format, you can replace the built-in serialization with `.serialize()` method.
SuperAgent will automatically serialize JSON and forms.
You can setup automatic serialization for other types as well:

```js
request.serialize['application/xml'] = function (obj) {
return 'string generated from obj';
};

//going forward, all requests with a Content-type of
//'application/xml' will be automatically serialized
```
If you want to send the payload in a custom format, you can replace
the built-in serialization with the `.serialize()` method on a per-request basis:

```js
request
.post('/user')
.send({foo: 'bar'})
.serialize(function serializer(obj) {
return 'string generated from obj';
});
```
## Retrying requests

When given the `.retry()` method, SuperAgent will automatically retry requests, if they fail in a way that is transient or could be due to a flaky Internet connection.
Expand Down Expand Up @@ -305,7 +325,27 @@ request

## Parsing response bodies

SuperAgent will parse known response-body data for you, currently supporting `application/x-www-form-urlencoded`, `application/json`, and `multipart/form-data`.
SuperAgent will parse known response-body data for you,
currently supporting `application/x-www-form-urlencoded`,
`application/json`, and `multipart/form-data`. You can setup
automatic parsing for other response-body data as well:

```js
//browser
request.parse['application/xml'] = function (str) {
return {'object': 'parsed from str'};
};

//node
request.parse['application/xml'] = function (res, cb) {
//parse response text and set res.body here

cb(null, res);
};

//going forward, responses of type 'application/xml'
//will be parsed automatically
```

You can set a custom parser (that takes precedence over built-in parsers) with the `.buffer(true).parse(fn)` method. If response buffering is not enabled (`.buffer(false)`) then the `response` event will be emitted without waiting for the body parser to finish, so `response.body` won't be available.

Expand Down

0 comments on commit 276244c

Please sign in to comment.