koa-lite/docs/api/response.md

Response

A Koa Response object is an abstraction on top of node's vanilla response object, providing additional functionality that is useful for every day HTTP server development.

API

res.header

Response header object.

res.status

Get response status.

res.status=

Set response status via numeric code or case-insensitive string:

• 100 "continue"
• 101 "switching protocols"
• 102 "processing"
• 200 "ok"
• 201 "created"
• 202 "accepted"
• 203 "non-authoritative information"
• 204 "no content"
• 205 "reset content"
• 206 "partial content"
• 207 "multi-status"
• 300 "multiple choices"
• 301 "moved permanently"
• 302 "moved temporarily"
• 303 "see other"
• 304 "not modified"
• 305 "use proxy"
• 307 "temporary redirect"
• 400 "bad request"
• 401 "unauthorized"
• 402 "payment required"
• 403 "forbidden"
• 404 "not found"
• 405 "method not allowed"
• 406 "not acceptable"
• 407 "proxy authentication required"
• 408 "request time-out"
• 409 "conflict"
• 410 "gone"
• 411 "length required"
• 412 "precondition failed"
• 413 "request entity too large"
• 414 "request-uri too large"
• 415 "unsupported media type"
• 416 "requested range not satisfiable"
• 417 "expectation failed"
• 418 "i'm a teapot"
• 422 "unprocessable entity"
• 423 "locked"
• 424 "failed dependency"
• 425 "unordered collection"
• 426 "upgrade required"
• 428 "precondition required"
• 429 "too many requests"
• 431 "request header fields too large"
• 500 "internal server error"
• 501 "not implemented"
• 502 "bad gateway"
• 503 "service unavailable"
• 504 "gateway time-out"
• 505 "http version not supported"
• 506 "variant also negotiates"
• 507 "insufficient storage"
• 509 "bandwidth limit exceeded"
• 510 "not extended"
• 511 "network authentication required"

NOTE: don't worry too much about memorizing these strings, if you have a typo an error will be thrown, displaying this list so you can make a correction.

res.length=

Set response Content-Length to the given value.

res.length

Return response Content-Length as a number when present, or deduce from res.body when possible, or undefined.

res.body

Get response body. When res.body is null and res.status is still 200 it is considered a 404. This is to prevent the developer from manually specifying this.status = 200 on every response.

res.body=

Set response body to one of the following:

• string written
• Buffer written
• Stream piped
• Object json-stringified
• null no content response

String

The Content-Type is defaulted to text/html or text/plain, both with a default charset of utf-8. The Content-Length field is also set.

Buffer

The Content-Type is defaulted to application/octet-stream, and Content-Length is also set.

Stream

The Content-Type is defaulted to application/octet-stream.

Object

The Content-Type is defaulted to application/json.

Notes

To alter the JSON response formatting use the app.jsonSpaces setting, for example to compress JSON responses set:

app.jsonSpaces = 0;

res.get(field)

Get a response header field value with case-insensitive field.

var etag = this.get('ETag');

res.set(field, value)

Set response header field to value:

this.set('Cache-Control', 'no-cache');

res.set(fields)

Set several response header fields with an object:

this.set({
  'Etag': '1234',
  'Last-Modified': date
});

res.type

Get response Content-Type void of parameters such as "charset".

var ct = this.type;
// => "image/png"

res.type=

Set response Content-Type via mime string or file extension.

this.type = 'text/plain; charset=utf-8';
this.type = 'image/png';
this.type = '.png';
this.type = 'png';

Note: when appropriate a charset is selected for you, for example res.type = 'html' will default to "utf-8", however when explicitly defined in full as res.type = 'text/html' no charset is assigned.

res.redirect(url, [alt])

Perform a 302 redirect to url.

The string "back" is special-cased to provide Referrer support, when Referrer is not present alt or "/" is used.

this.redirect('back');
this.redirect('back', '/index.html');
this.redirect('/login');
this.redirect('http://google.com');

To alter the default status of 302 or the response body simply re-assign after this call:

this.redirect('/cart');
this.status = 301;
this.body = 'Redirecting to shopping cart';

res.attachment([filename])

Set Content-Disposition to "attachment" to signal the client to prompt for download. Optionally specify the filename of the download.

res.headerSent

Check if a response header has already been sent. Useful for seeing if the client may be notified on error.