Response objects

The response object specifies the following properties:

• body: Buffer | string

Response body as a string or buffer. Can be set directly or using someof the response methods.

• context: Context

The service context in which the router was mounted(rather than the context in which the route was defined).

• headers: object

The raw headers object.

• statusCode: number

Status code of the response. Defaults to 200 (body set and not an emptystring or buffer) or 204 (otherwise) if not changed from undefined.

attachment

res.attachment([filename]): this

Sets the content-disposition header to indicate the response is adownloadable file with the given name.

Note: This does not actually modify the response body or access thefile system. To send a file from the file system see the download orsendFile methods.

Arguments

• filename: string (optional)

Name of the downloadable file in the response body.

If present, the extension of the filename will be used to set the responsecontent-type if it has not yet been set.

Returns the response object.

cookie

res.cookie(name, value, [options]): this

Sets a cookie with the given name.

Arguments

• name: string

Name of the cookie.

• value: string

Value of the cookie.

• options: object (optional)

An object with any of the following properties:

• ttl: number (optional)

Time to live of the cookie in seconds.

• algorithm: string (Default: "sha256")

Algorithm that will be used to sign the cookie.

• secret: string (optional)

Secret that will be used to sign the cookie.

If a secret is specified, the cookie’s signature will be stored in a secondcookie with the same options, the same name and the suffix .sig.Otherwise no signature will be added.

• path: string (optional)

Path for which the cookie should be issued.

• domain: string (optional)

Domain for which the cookie should be issued.

• secure: boolean (Default: false)

Whether the cookie should be marked as secure (i.e. HTTPS/SSL-only).

• httpOnly: boolean (Default: false)

Whether the cookie should be marked as HTTP-only (rather than also exposingit to client-side code).

If a string is passed instead of an options object it will be interpreted asthe secret option.

If a number is passed instead of an options object it will be interpreted asthe ttl option.

Returns the response object.

download

res.download(path, [filename]): this

The equivalent of calling res.attachment(filename).sendFile(path).

Arguments

• path: string

Path to the file on the local filesystem to be sent as the response body.

• filename: string (optional)

Filename to indicate in the content-disposition header.

If omitted the path will be used instead.

Returns the response object.

getHeader

res.getHeader(name): string

Gets the value of the header with the given name.

Arguments

• name: string

Name of the header to get.

Returns the value of the header or undefined.

json

res.json(data): this

Sets the response body to the JSON string value of the given data.

Arguments

• data: any

The data to be used as the response body.

Returns the response object.

redirect

res.redirect([status], path): this

Redirects the response by setting the response location header and status code.

Arguments

• status: number | string (optional)

Response status code to set.

If the status code is the string value "permanent" it will be treated asthe value 301.

If the status code is a string it will be converted to a numeric status codeusing the statuses module first.

If the status code is omitted but the response status has not already beenset, the response status will be set to 302.

• path: string

URL to set the location header to.

Returns the response object.

removeHeader

res.removeHeader(name): this

Removes the header with the given name from the response.

Arguments

• name: string

Name of the header to remove.

Returns the response object.

send

res.send(data, [type]): this

Sets the response body to the given data with respect to the responsedefinition for the response’s current status code.

Arguments

• data: any

The data to be used as the response body. Will be converted according theresponse definition for the response’s currentstatus code (or 200) in the following way:

If the data is an ArangoDB result set, it will be converted to an array first.

If the response definition specifies a model with a forClient method,that method will be applied to the data first. If the data is an array andthe response definition has the multiple flag set, the method will beapplied to each entry individually instead.

Finally the data will be processed by the response type handler to convertthe response body to a string or buffer.

• type: string (Default: "auto")

Content-type of the response body.

If set to "auto" the first MIME type specified in theresponse definition for the response’s currentstatus code (or 200) will be used instead.

If set to "auto" and no response definition exists, the MIME type willbe determined the following way:

If the data is a buffer the MIME type will be set to binary(application/octet-stream).

If the data is an object the MIME type will be set to JSON and the datawill be converted to a JSON string.

Otherwise the MIME type will be set to HTML and the data will beconverted to a string.

Returns the response object.

sendFile

res.sendFile(path, [options]): this

Sends a file from the local filesystem as the response body.

Arguments

• path: string

Path to the file on the local filesystem to be sent as the response body.

If no content-type header has been set yet, the extension of the filenamewill be used to set the value of that header.

• options: object (optional)

An object with any of the following properties:

• lastModified: boolean (optional)

If set to true or if no last-modified header has been set yet and thevalue is not set to false the last-modified header will be set to themodification date of the file in milliseconds.

Returns the response object.

Examples

// Send the file "favicon.ico" from this service's folder
res.sendFile(module.context.fileName('favicon.ico'));

sendStatus

res.sendStatus(status): this

Sends a plaintext response for the given status code.The response status will be set to the given status code, the response bodywill be set to the status message corresponding to that status code.

Arguments

• status: number | string

Response status code to set.

If the status code is a string it will be converted to a numeric status codeusing the statuses module first.

Returns the response object.

setHeader / set

res.setHeader(name, value): this

res.set(name, value): this

res.set(headers): this

Sets the value of the header with the given name.

Arguments

• name: string

Name of the header to set.

• value: string

Value to set the header to.

• headers: object

Header object mapping header names to values.

Returns the response object.

status

res.status(status): this

Sets the response status to the given status code.

Arguments

• status: number | string

Response status code to set.

If the status code is a string it will be converted to a numeric statuscode using the statuses module first.

Returns the response object.

throw

res.throw(status, [reason], [options]): void

Throws an HTTP exception for the given status, which will be handled by Foxxto serve the appropriate JSON error response.

Arguments

• status: number | string

Response status code to set.

If the status code is a string it will be converted to a numeric status codeusing the statuses module first.

If the status code is in the 500-range (500-599), its stacktrace will alwaysbe logged as if it were an unhandled exception.

If development mode is enabled, the error’s stacktrace will be logged as awarning if the status code is in the 400-range (400-499) or as a regularmessage otherwise.

• reason: string (optional)

Message for the exception.

If omitted, the status message corresponding to the status code will beused instead.

• options: object (optional)

An object with any of the following properties:

• cause: Error (optional)

Cause of the exception that will be logged as part of the error’s stacktrace(recursively, if the exception also has a cause property and so on).

• extra: object (optional)

Additional properties that will be added to the error response bodygenerated by Foxx.

If development mode is enabled, an exception property will be added tothis value containing the error message and a stacktrace property willbe added containing an array with each line of the error’s stacktrace.

If an error is passed instead of an options object it will be interpreted asthe cause option. If no reason was provided the error’s message will beused as the reason instead.

Returns nothing.

type

res.type([type]): string

Sets the response content-type to the given type if provided or returns thepreviously set content-type.

Arguments

• type: string (optional)

Content-type of the response body.

Unlike res.set('content-type', type) file extensions can be provided asvalues and will be translated to the corresponding MIME type (e.g. jsonbecomes application/json).

Returns the content-type of the response body.

vary

res.vary(names): this

res.vary(…names): this

This method wraps the vary header manipulation method of thevary module for the current response.

The given names will be added to the response’s vary header if not already present.

Returns the response object.

Examples

res.vary('user-agent');
res.vary('cookie');
res.vary('cookie'); // duplicates will be ignored
// -- or --
res.vary('user-agent', 'cookie');
// -- or --
res.vary(['user-agent', 'cookie']);

write

res.write(data): this

Appends the given data to the response body.

Arguments

• data: string | Buffer

Data to append.

If the data is a buffer the response body will be converted to a buffer first.

If the response body is a buffer the data will be converted to a buffer first.

If the data is an object it will be converted to a JSON string first.

If the data is any other non-string value it will be converted to a string first.

Returns the response object.