WebApps 2

router

Routing

Routes handle how a WebApp responds to client requests. All WebApps have a unique segment in the URL where routing information is kept. WebApp routes differ from application routes since WebApp routes are local and should be used to keep state for a single WebApp. The router object provides methods to respond to the following request methods:

  • GET
  • PUT
  • POST
  • DELETE
  • PATCH (@since 2023.02.1)

A route definition has the following structure:

router.method(path, handler);

Basic examples:

// retrieve an instance of the router object
import router from '@sitevision/api/common/router';

// respond to a GET-request to the root route ('/')
router.get('/', (req, res) => {
   res.send('Hello from my WebApp!');
});

// respond to a GET-request to '/user'
router.get('/user', (req, res) => {
   res.send('Hello from user route');
});

Middleware

A middleware function is a function that have access to the request object (req), response object (res) and a function (next) triggering the next function in the request-response chain. The next function will either be another middleware or the actual route function. Middleware functions are executed every time the app receives a request matching a route.

Middleware functions are registered using the router.use-method:

import router from '@sitevision/api/common/router';

// middleware that will be executed every time the app recives a request
router.use((req, res, next) => {
   if (req.method === 'PUT') {
      // do something
   }
   // trigger next function in the stack (next middleware or route function)
   next();
});

router.get('/', (req, res) => {
   res.send('Hello');
});

Requests may be terminated and altered within a middleware. Keep in mind that the next()-function must be called in order to pass over control to the next function in the stack.

Multiple middleware functions may be registered and they will be executed in the order they are registered, i.e. top-down.

import router from '@sitevision/api/common/router';

router.use((req, res, next) => {
   console.info('Hello from first');
   next();
});

router.use((req, res, next) => {
   console.info('Hello from second');
   next();
});

router.get('/', (req, res) => {
   console.info('Hello from route');
   res.send('Hello');
});

// => 'Hello from first'
// => 'Hello from second'
// => 'Hello from route'

Middleware can be a very useful tool when managing persissons in your application to ensure all endpoints are secured. A basic example is available on GitHub.

Route parameters

Route parameters are used to capture a value in the URL. Below is an example of a path that will capture id on the /user route.

// GET /user/123
router.get('/user/:id', (req, res) => {
   // route is matched and {id: 123} will be populated in the req.params object
});

Router methods

router.getUrl(path [, queryStringParameters])

Returns a URL given a path. Provide queryStringParameters as an object to include query string parameters. The URL will match configured paths in index.js.

router.getStandaloneUrl(path [, queryStringParameters])

Returns a URL given a path. This type or URL is used to execute a route standalone, i.e. it will not be part of page rendering. This is very useful when you only want to target your route without any side effects. The SDK documentation contains example of client-side usage.