2017-10-21 07:35:39 +02:00
---
title: Response API
permalink: /docs/response-api/
---
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
### Table of Contents
2018-04-20 11:44:05 -07:00
- [Response ](#response )
- [cache ](#cache )
- [noCache ](#nocache )
- [charSet ](#charset )
- [header ](#header )
- [json ](#json )
- [link ](#link )
- [send ](#send )
- [sendRaw ](#sendraw )
- [set ](#set )
- [status ](#status )
- [redirect ](#redirect )
- [redirect ](#redirect-1 )
- [redirect ](#redirect-2 )
2017-10-21 07:35:39 +02:00
## Response
**Extends http.ServerResponse **
2017-10-24 22:22:30 +02:00
Wraps all of the node
2018-04-20 11:44:05 -07:00
[http.ServerResponse ](https://nodejs.org/docs/latest/api/http.html )
2017-10-21 07:35:39 +02:00
APIs, events and properties, plus the following.
### cache
Sets the `cache-control` header.
**Parameters **
2018-04-20 11:44:05 -07:00
- `type` * * [String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String )** value of the header
2017-10-21 07:35:39 +02:00
(`"public"` or `"private"` ) (optional, default `"public"` )
2018-04-20 11:44:05 -07:00
- `options` * * [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object )?** an options object
- `options.maxAge` * * [Number ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number )** max-age in seconds
2017-10-21 07:35:39 +02:00
2018-04-20 11:44:05 -07:00
Returns * * [String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String )** the value set to the header
2017-10-21 07:35:39 +02:00
### noCache
Turns off all cache related headers.
2018-04-20 11:44:05 -07:00
Returns * * [Response ](#response )** self, the response object
2017-10-21 07:35:39 +02:00
### charSet
Appends the provided character set to the response's `Content-Type` .
**Parameters **
2018-04-20 11:44:05 -07:00
- `type` * * [String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String )** char-set value
2017-10-21 07:35:39 +02:00
**Examples **
``` javascript
res . charSet ( 'utf-8' ) ;
```
2018-04-20 11:44:05 -07:00
Returns * * [Response ](#response )** self, the response object
2017-10-21 07:35:39 +02:00
### header
Sets headers on the response.
**Parameters **
2018-04-20 11:44:05 -07:00
- `key` * * [String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String )** the name of the header
- `value` * * [String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String )** the value of the header
2017-10-21 07:35:39 +02:00
**Examples **
2017-10-24 22:22:30 +02:00
_If only key is specified, return the value of the header.
2017-10-21 07:35:39 +02:00
If both key and value are specified, set the response header._
``` javascript
res . header ( 'Content-Length' ) ;
// => undefined
res . header ( 'Content-Length' , 123 ) ;
// => 123
res . header ( 'Content-Length' ) ;
// => 123
res . header ( 'foo' , new Date ( ) ) ;
// => Fri, 03 Feb 2012 20:09:58 GMT
```
2017-10-24 22:22:30 +02:00
_`header()` can also be used to automatically chain header values
2017-10-21 07:35:39 +02:00
when applicable:_
``` javascript
res . header ( 'x-foo' , 'a' ) ;
res . header ( 'x-foo' , 'b' ) ;
// => { 'x-foo': ['a', 'b'] }
```
2018-04-20 11:44:05 -07:00
Returns * * [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object )** the retrieved value or the value that was set
2017-10-21 07:35:39 +02:00
### json
Syntatic sugar for:
``` js
res . contentType = 'json' ;
res . send ( { hello : 'world' } ) ;
```
**Parameters **
2018-04-20 11:44:05 -07:00
- `code` * * [Number ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number )?** http status code
- `body` * * [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object )?** value to json.stringify
- `headers` * * [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object )?** headers to set on the response
2017-10-21 07:35:39 +02:00
**Examples **
``` javascript
res . header ( 'content-type' , 'json' ) ;
res . send ( { hello : 'world' } ) ;
```
2018-04-20 11:44:05 -07:00
Returns * * [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object )** the response object
2017-10-21 07:35:39 +02:00
### link
Sets the link header.
**Parameters **
2018-04-20 11:44:05 -07:00
- `key` * * [String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String )** the link key
- `value` * * [String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String )** the link value
2017-10-21 07:35:39 +02:00
2018-04-20 11:44:05 -07:00
Returns * * [String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String )** the header value set to res
2017-10-21 07:35:39 +02:00
### send
Sends the response object. pass through to internal `__send` that uses a
formatter based on the `content-type` header.
**Parameters **
2018-04-20 11:44:05 -07:00
- `code` * * [Number ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number )?** http status code
- `body` * * ([Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object ) \| [Buffer ](https://nodejs.org/api/buffer.html ) \| [Error ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error ))?** the content to send
- `headers` * * [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object )?** any add'l headers to set
2017-10-21 07:35:39 +02:00
**Examples **
2017-10-24 22:22:30 +02:00
_You can use send() to wrap up all the usual writeHead(), write(), end()
calls on the HTTP API of node.
2017-11-02 19:00:16 +01:00
You can pass send either a `code` and `body` , or just a body. body can be
an `Object` , a `Buffer` , or an `Error` .
When you call `send()` , restify figures out how to format the response
based on the `content-type` ._
2017-10-21 07:35:39 +02:00
``` javascript
res . send ( { hello : 'world' } ) ;
res . send ( 201 , { hello : 'world' } ) ;
res . send ( new BadRequestError ( 'meh' ) ) ;
```
2018-04-20 11:44:05 -07:00
Returns * * [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object )** the response object
2017-10-21 07:35:39 +02:00
### sendRaw
2017-11-02 19:00:16 +01:00
Like `res.send()` , but skips formatting. This can be useful when the
payload has already been preformatted.
2017-10-21 07:35:39 +02:00
Sends the response object. pass through to internal `__send` that skips
formatters entirely and sends the content as is.
**Parameters **
2018-04-20 11:44:05 -07:00
- `code` * * [Number ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number )?** http status code
- `body` * * ([Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object ) \| [Buffer ](https://nodejs.org/api/buffer.html ) \| [Error ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error ))?** the content to send
- `headers` * * [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object )?** any add'l headers to set
2017-10-21 07:35:39 +02:00
2018-04-20 11:44:05 -07:00
Returns * * [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object )** the response object
2017-10-21 07:35:39 +02:00
### set
2017-10-24 22:22:30 +02:00
Sets multiple header(s) on the response.
2017-10-21 07:35:39 +02:00
Uses `header()` underneath the hood, enabling multi-value headers.
**Parameters **
2018-04-20 11:44:05 -07:00
- `name` * * ([String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String ) \| [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object ))** name of the header or
2017-11-02 19:00:16 +01:00
`Object` of headers
2018-04-20 11:44:05 -07:00
- `val` * * [String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String )** value of the header
2017-10-21 07:35:39 +02:00
**Examples **
``` javascript
res . header ( 'x-foo' , 'a' ) ;
res . set ( {
'x-foo' , 'b' ,
'content-type' : 'application/json'
} ) ;
// =>
// {
// 'x-foo': [ 'a', 'b' ],
// 'content-type': 'application/json'
// }
```
2018-04-20 11:44:05 -07:00
Returns * * [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object )** self, the response object
2017-10-21 07:35:39 +02:00
### status
Sets the http status code on the response.
**Parameters **
2018-04-20 11:44:05 -07:00
- `code` * * [Number ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number )** http status code
2017-10-21 07:35:39 +02:00
**Examples **
``` javascript
res . status ( 201 ) ;
```
2018-04-20 11:44:05 -07:00
Returns * * [Number ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number )** the status code passed in
2017-10-21 07:35:39 +02:00
### redirect
Redirect is sugar method for redirecting.
**Parameters **
2018-04-20 11:44:05 -07:00
- `options` * * [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object )** url or an options object to configure a redirect
- `options.secure` * * [Boolean ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean )?** whether to redirect to http or https
- `options.hostname` * * [String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String )?** redirect location's hostname
- `options.pathname` * * [String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String )?** redirect location's pathname
- `options.port` * * [String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String )?** redirect location's port number
- `options.query` * * [String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String )?** redirect location's query string
2017-11-02 19:00:16 +01:00
parameters
2018-04-20 11:44:05 -07:00
- `options.overrideQuery` * * [Boolean ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean )?** if true, `options.query`
2017-11-02 19:00:16 +01:00
stomps over any existing query
parameters on current URL.
by default, will merge the two.
2018-04-20 11:44:05 -07:00
- `options.permanent` * * [Boolean ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean )?** if true, sets 301. defaults to 302.
- `next` * * [Function ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function )** mandatory, to complete the response and trigger
2017-11-02 19:00:16 +01:00
audit logger.
2017-10-21 07:35:39 +02:00
**Examples **
``` javascript
res . redirect ( { ... } , next ) ;
```
2017-10-24 22:22:30 +02:00
_A convenience method for 301/302 redirects. Using this method will tell
restify to stop execution of your handler chain.
2017-10-21 07:35:39 +02:00
You can also use an options object. `next` is required._
``` javascript
res . redirect ( {
hostname : 'www.foo.com' ,
pathname : '/bar' ,
port : 80 , // defaults to 80
secure : true , // sets https
permanent : true ,
query : {
a : 1
}
} , next ) ; // => redirects to 301 https://www.foo.com/bar?a=1
```
2018-04-20 11:44:05 -07:00
Returns * * [undefined ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined )**
2017-10-21 07:35:39 +02:00
### redirect
Redirect with code and url.
**Parameters **
2018-04-20 11:44:05 -07:00
- `code` * * [Number ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number )** http redirect status code
- `url` * * [String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String )** redirect url
- `next` * * [Function ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function )** mandatory, to complete the response and trigger
2017-10-21 07:35:39 +02:00
audit logger.
**Examples **
``` javascript
res . redirect ( 301 , 'www.foo.com' , next ) ;
```
2018-04-20 11:44:05 -07:00
Returns * * [undefined ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined )**
2017-10-21 07:35:39 +02:00
### redirect
Redirect with url.
**Parameters **
2018-04-20 11:44:05 -07:00
- `url` * * [String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String )** redirect url
- `next` * * [Function ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function )** mandatory, to complete the response and trigger
2017-10-21 07:35:39 +02:00
audit logger.
**Examples **
``` javascript
res . redirect ( 'www.foo.com' , next ) ;
res . redirect ( '/foo' , next ) ;
```
2018-04-20 11:44:05 -07:00
Returns * * [undefined ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined )**
