Routers

const createRouter = require('@arangodb/foxx/router');

Routers let you define routes that extend ArangoDB’s HTTP API with custom endpoints.

Routers need to be mounted using the use method of aservice context to expose their HTTP routes at a service’s mount path.

You can pass routers between services mounted in the same databaseas dependencies. You can even nest routerswithin each other.

Creating a router

createRouter(): Router

This returns a new, clean router object that has not yet been mounted in theservice and can be exported like any other object.

Request handlers

router.get([path], […middleware], handler, [name]): Endpoint

router.post([path], […middleware], handler, [name]): Endpoint

router.put([path], […middleware], handler, [name]): Endpoint

router.patch([path], […middleware], handler, [name]): Endpoint

router.delete([path], […middleware], handler, [name]): Endpoint

router.all([path], […middleware], handler, [name]): Endpoint

These methods let you specify routes on the router.The all method defines a route that will match any supported HTTP verb, theother methods define routes that only match the HTTP verb with the same name.

Arguments

• path: string (Default: "/")

The path of the request handler relative to the base path the Router is mounted at.If omitted, the request handler will handle requests to the base path of the Router.For information on defining dynamic routes see the section onpath parameters in the chapter on router endpoints.

• middleware: Function (optional)

Zero or more middleware functions that take the following arguments:

• req: Request

An incoming server request object.

• res: Response

An outgoing server response object.

• next: Function

A callback that passes control over to the next middleware functionand returns when that function has completed.

If a truthy argument is passed, that argument will be thrown as an error.

If there is no next middleware function, the handler will beinvoked instead (see below).

• handler: Function

A function that takes the following arguments:

• req: Request

An incoming server request object.

• res: Response

An outgoing server response.

• name: string (optional)

A name that can be used to generate URLs for the endpoint.For more information see the reverse method of the request object.

Returns an Endpoint for the route.

Examples

Simple index route:

router.get(function (req, res) {
  res.set('content-type', 'text/plain');
  res.write('Hello World!');
});

Restricting access to authenticated ArangoDB users:

router.get('/secrets', function (req, res, next) {
  if (req.arangoUser) {
    next();
  } else {
    res.throw(404, 'Secrets? What secrets?');
  }
}, function (req, res) {
  res.download('allOurSecrets.zip');
});

Multiple middleware functions:

function counting (req, res, next) {
  if (!req.counter) req.counter = 0;
  req.counter++;
  next();
  req.counter--;
}
router.get(counting, counting, counting, function (req, res) {
  res.json({counter: req.counter}); // {"counter": 3}
});

Mounting child routers and middleware

router.use([path], middleware, [name]): Endpoint

The use method lets you mount a child router or middleware at a given path.

Arguments

• path: string (optional)

The path of the middleware relative to the base path the Router is mounted at.If omitted, the middleware will handle requests to the base path of the Router.For information on defining dynamic routes see the section onpath parameters in the chapter on router endpoints.

• middleware: Router | Middleware

An unmounted router object or a middleware.

• name: string (optional)

A name that can be used to generate URLs for endpoints of this router.For more information see the reverse method of the request object.Has no effect if handler is a Middleware.

Returns an Endpoint for the middleware or child router.