Request objects

The request object specifies the following properties:

• arangoUser: string | null

The authenticated ArangoDB username used to make the request.This value is only set if authentication is enabled in ArangoDB and therequest set an authorization header ArangoDB was able to verify.You are strongly encouraged to implementyour own authentication logic for your own servicesbut this property can be useful if you need to integrate with ArangoDB’sown authentication mechanisms.

• arangoVersion: number

The numeric value of the x-arango-version header or the numeric versionof the ArangoDB server (e.g. 30102 for version 3.1.2) if no valid headerwas provided.

• auth: object | null

The credentials supplied in the authorization header if any.

If the request uses basic authentication, the value is an object like{basic: {username: string}} or{basic: {username: string, password: string}} or{basic: {}} (if the credentials were malformed or empty).

If the request uses bearer authentication, the value is an object like{bearer: string}.

• baseUrl: string

Root-relative base URL of the service, i.e. the prefix "/db/" followedby the value of _database.

• body: any

The processed and validated request body for the current route.If no body has been defined for the current route, the value will beidentical to rawBody.

For details on how request bodies can be processed and validated by Foxxsee the body method of the endpoint object.

• context: Context

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

• database: string

The name of the database in which the request is being handled, e.g. "_system".

• headers: object

The raw headers object.

For details on how request headers can be validated by Foxx see theheader method of the endpoint object.

• hostname: string

The hostname (domain name) indicated in the request headers.

Defaults to the hostname portion (i.e. excluding the port) of the Hostheader and falls back to the listening address of the server.

• method: string

The HTTP verb used to make the request, e.g. "GET".

• originalUrl: string

Root-relative URL of the request, i.e. path followed by the raw queryparameters, if any.

• path: string

Database-relative path of the request URL (not including the query parameters).

• pathParams: object

An object mapping the names of path parameters of the current route totheir validated values.

For details on how path parameters can be validated by Foxx see thepathParam method of the endpoint object.

• port: number

The port indicated in the request headers.

Defaults to the port portion (i.e. excluding the hostname) of the Hostheader and falls back to the listening port or the appropriate defaultport (443 for HTTPS or 80 for HTTP, depending on secure) if theheader only indicates a hostname.

If the request was made using a trusted proxy (see trustProxy),this is set to the port portion of the X-Forwarded-Host header(or appropriate default port) if present.

• protocol: string

The protocol used for the request.

Defaults to "https" or "http" depending on whether ArangoDB isconfigured to use SSL or not.

If the request was made using a trusted proxy (see trustProxy),this is set to the value of the X-Forwarded-Proto header if present.

• queryParams: object

An object mapping the names of query parameters of the current route totheir validated values.

For details on how query parameters can be validated by Foxx see thequeryParam method of the endpoint object.

• rawBody: Buffer

The raw, unparsed, unvalidated request body as a buffer.

• remoteAddress: string

The IP of the client that made the request.

If the request was made using a trusted proxy (see trustProxy),this is set to the first IP listed in the X-Forwarded-For header if present.

• remoteAddresses: Array<string>

A list containing the IP addresses used to make the request.

Defaults to the value of remoteAddress wrapped in an array.

If the request was made using a trusted proxy (see trustProxy),this is set to the list of IPs specified in the X-Forwarded-For header if present.

• remotePort: number

The listening port of the client that made the request.

If the request was made using a trusted proxy (see trustProxy),this is set to the port specified in the X-Forwarded-Port header if present.

• secure: boolean

Whether the request was made over a secure connection (i.e. HTTPS).

This is set to false when protocol is "http" and true whenprotocol is "https".

• suffix: string

The trailing path relative to the current route if the current route endsin a wildcard (e.g. /something/*).

Note: Starting with ArangoDB 3.2 is passed into the service as-is, i.e.percentage escape sequences like %2F will no longer be unescaped.Also note that the suffix may contain path segments like .. which may havespecial meaning if the suffix is used to build filesystem paths.

• trustProxy: boolean

Indicates whether the request was made using a trusted proxy.If the origin server’s address was specified in the ArangoDB configurationusing —frontend.trusted-proxy or the service’s trustProxy setting isenabled, this will be true, otherwise it will be false.

• url: string

The URL of the request.

• xhr: boolean

Whether the request indicates it was made within a browser using AJAX.

This is set to true if the X-Requested-With header is present and isa case-insensitive match for the value "xmlhttprequest".

Note that this value does not guarantee whether the request was made frominside a browser or whether AJAX was used and is merely a conventionestablished by JavaScript frameworks like jQuery.

accepts

req.accepts(types): string | false

req.accepts(…types): string | false

req.acceptsCharsets(charsets): string | false

req.acceptsCharsets(…charsets): string | false

req.acceptsEncodings(encodings): string | false

req.acceptsEncodings(…encodings): string | false

req.acceptsLanguages(languages): string | false

req.acceptsLanguages(…languages): string | false

These methods wrap the corresponding content negotiation methods of theaccepts module for the current request.

Examples

if (req.accepts(['json', 'html']) === 'html') {
  // Client explicitly prefers HTML over JSON
  res.write('<h1>Client prefers HTML</h1>');
} else {
  // Otherwise just send JSON
  res.json({success: true});
}

cookie

req.cookie(name, options): string | null

Gets the value of a cookie by name.

Arguments

• name: string

Name of the cookie.

• options: object (optional)

An object with any of the following properties:

• secret: string (optional)

Secret that was used to sign the cookie.

If a secret is specified, the cookie’s signature is expected to be presentin a second cookie with the same name and the suffix .sig.Otherwise the signature (if present) will be ignored.

• algorithm: string (Default: "sha256")

Algorithm that was used to sign the cookie.

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

Returns the value of the cookie or null if the cookie is not set or itssignature is invalid.

get / header

req.get(name): string

req.header(name): string

Gets the value of a header by name. You can validate request headers using theheader method of the endpoint.

Arguments

• name: string

Name of the header.

Returns the header value.

is

req.is(types): string

req.is(…types): string

This method wraps the (request body) content type detection method of thetype-is module for the current request.

Examples

const type = req.is('html', 'application/xml', 'application/*+xml');
if (type === false) { // no match
  handleDefault(req.rawBody);
} else if (type === 'html') {
  handleHtml(req.rawBody);
} else { // is XML
  handleXml(req.rawBody);
}

json

req.json(): any

Attempts to parse the raw request body as JSON and returns the result.

It is generally more useful to define arequest body on the endpoint and use the req.bodyproperty instead.

Returns undefined if the request body is empty. May throw a SyntaxErrorif the body could not be parsed.

makeAbsolute

req.makeAbsolute(path, [query]): string

Resolves the given path relative to the req.context.service’s mount pathto a full URL.

Arguments

• path: string

The path to resovle.

• query: string | object

A string or object with query parameters to add to the URL.

Returns the formatted absolute URL.

params

req.param(name): any

Arguments

Looks up a parameter by name, preferring pathParams over queryParams.

It’s probably better style to use the req.pathParams or req.queryParamsobjects directly.

• name: string

Name of the parameter.

Returns the (validated) value of the parameter.

range

req.range([size]): Ranges | number

This method wraps the range header parsing method of therange-parser module for the current request.

Arguments

• size: number (Default: Infinity)

Length of the satisfiable range (e.g. number of bytes in the full response).If present, ranges exceeding the size will be considered unsatisfiable.

Returns undefined if the Range header is absent, -2 if the header ispresent but malformed, -1 if the range is invalid (e.g. start offset islarger than end offset) or unsatisfiable for the given size.

Otherwise returns an array of objects with the properties start and end_values for each range. The array has an additional property _type indicatingthe request range type.

Examples

console.log(req.headers.range); // "bytes=40-80"
const ranges = req.range(100);
console.log(ranges); // [{start: 40, end: 80}]
console.log(ranges.type); // "bytes"

reverse

req.reverse(name, [params]): string

Looks up the URL of a named route for the given parameters.

Arguments

• name: string

Name of the route to look up.

• params: object (optional)

An object containing values for the (path or query) parameters of the route.

Returns the URL of the route for the given parameters.

Examples

router.get('/items/:id', function (req, res) {
  /* ... */
}, 'getItemById');
router.post('/items', function (req, res) {
  // ...
  const url = req.reverse('getItemById', {id: createdItem._key});
  res.set('location', req.makeAbsolute(url));
});