Response API

Table of Contents

• Response
  • cache
  • noCache
  • charSet
  • header
  • json
  • link
  • send
  • sendRaw
  • set
  • status
  • redirect
  • redirect
  • redirect

Response

Extends http.ServerResponse

Wraps all of the node http.ServerResponse APIs, events and properties, plus the following.

cache

Sets the cache-control header.

Parameters

• type String value of the header ("public" or "private") (optional, default "public")
• options Object? an options object
  • options.maxAge Number max-age in seconds

Returns String the value set to the header

noCache

Turns off all cache related headers.

Returns Response self, the response object

charSet

Appends the provided character set to the response’s Content-Type.

Parameters

• type String char-set value

Examples

res.charSet('utf-8');

Returns Response self, the response object

header

Sets headers on the response.

Parameters

• key String the name of the header
• value String the value of the header

Examples

If only key is specified, return the value of the header. If both key and value are specified, set the response header.

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

header() can also be used to automatically chain header values when applicable:

res.header('x-foo', 'a');
res.header('x-foo', 'b');
// => { 'x-foo': ['a', 'b'] }

Returns Object the retrieved value or the value that was set

json

Syntatic sugar for:

res.contentType = 'json';
res.send({hello: 'world'});

Parameters

• code Number? http status code
• body Object? value to json.stringify
• headers Object? headers to set on the response

Examples

res.header('content-type', 'json');
res.send({hello: 'world'});

Returns Object the response object

link

Sets the link header.

Parameters

• key String the link key
• value String the link value

Returns String the header value set to res

send

Sends the response object. pass through to internal __send that uses a formatter based on the content-type header.

Parameters

• code Number? http status code
• body (Object | Buffer | Error)? the content to send
• headers Object? any add’l headers to set

Examples

You can use send() to wrap up all the usual writeHead(), write(), end() calls on the HTTP API of node. 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.

res.send({hello: 'world'});
res.send(201, {hello: 'world'});
res.send(new BadRequestError('meh'));

Returns Object the response object

sendRaw

Like res.send(), but skips formatting. This can be useful when the payload has already been preformatted. Sends the response object. pass through to internal __send that skips formatters entirely and sends the content as is.

Parameters

• code Number? http status code
• body (Object | Buffer | Error)? the content to send
• headers Object? any add’l headers to set

Returns Object the response object

set

Sets multiple header(s) on the response. Uses header() underneath the hood, enabling multi-value headers.

Parameters

• name (String | Object) name of the header or Object of headers
• val String value of the header

Examples

res.header('x-foo', 'a');
res.set({
    'x-foo', 'b',
    'content-type': 'application/json'
});
// =>
// {
//    'x-foo': [ 'a', 'b' ],
//    'content-type': 'application/json'
// }

Returns Object self, the response object

status

Sets the http status code on the response.

Parameters

• code Number http status code

Examples

res.status(201);

Returns Number the status code passed in

redirect

Redirect is sugar method for redirecting.

Parameters

• options Object url or an options object to configure a redirect
  • options.secure Boolean? whether to redirect to http or https
  • options.hostname String? redirect location’s hostname
  • options.pathname String? redirect location’s pathname
  • options.port String? redirect location’s port number
  • options.query String? redirect location’s query string parameters
  • options.overrideQuery Boolean? if true, options.query stomps over any existing query parameters on current URL. by default, will merge the two.
  • options.permanent Boolean? if true, sets 301. defaults to 302.
• next Function mandatory, to complete the response and trigger audit logger.

Examples

res.redirect({...}, next);

A convenience method for 301/302 redirects. Using this method will tell restify to stop execution of your handler chain. You can also use an options object. next is required.

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

Returns undefined

redirect

Redirect with code and url.

Parameters

• code Number http redirect status code
• url String redirect url
• next Function mandatory, to complete the response and trigger audit logger.

Examples

res.redirect(301, 'www.foo.com', next);

Returns undefined

redirect

Redirect with url.

Parameters

• url String redirect url
• next Function mandatory, to complete the response and trigger audit logger.

Examples

res.redirect('www.foo.com', next);
res.redirect('/foo', next);

Returns undefined