Request Routing in Ioto

Ioto includes a flexible request routing engine that authenticates client HTTP requests and routes them to appropriate request handlers for processing.

This post is the fifth of a series on the Ioto embedded web server component. This post discusses request routing in Ioto.

The posts in the series are:

• Using the Ioto Embedded Web Server
• Extending Ioto with Custom Code
• Using Ioto to Generate Dynamic Responses
• Streaming Responses
• Request Routing
• User Authentication
• Using the Ioto Database
• Managing JSON data with Ioto
• Using the Kickstart Sample Device Manager

Route Configuration

Ioto request routes are defined in the config/web.json5 configuration file under the routes property.

A route defines how a request should be processed. The route specifies a matching URL prefix and required user authentication.

An Ioto configuration will typically have several routes. When a request is received, Ioto tests routes in sequence and selects the first matching route to handle the request.

For example:

routes: [
    {match: '/api/'},
    {match: '/admin/', role: 'admin'},
    {match: '/user/', role: 'user'},
    {},
],

Route Ordering

When multiple routes are defined, a client request will test each route in the order in which they are declared.

To process a request, Ioto compares the request URL with the route match property prefix. If the URL begins with the match property, the route is selected. So ordering is very important.

Route Matching

A route that terminates with ”/” will match any URL that begins with that pattern. If the route does not end with “/” it must match the entire URL path (without query or reference fragment).

The special route match pattern ”/” will match only the URL “/”. i.e. the site home page.

If the route does not contain a match pattern, all URLs will match. In this case, the route becomes a “catch-all”. In the example above, the last route will match any unmatched requests and will redirect the client to the /auth/login page.

Routes with longer or more qualified route match properties should be defined first before more general (shorter) routes.

Route Handlers

Ioto defines four request handlers:

• Redirect handler
• Action handler
• Upload handler
• Static handler

If an action routine has been defined for the matched route, one of the four handlers will be invoked. If the request matches a defined redirection, the client will be redirected to the new page. If the request is a file upload, the upload handler will be invoked. If an action routine is defined for the URL, the action handler will be used. Otherwise, the request will be served by static file handler.

If you need custom request processing, define an Action Routine that will be invoked for matching requests. In the action routine, you can perform any required custom processing or logic.

Redirects

Requests can be redirected by defining redirection rules in the config/web.json5 “redirect” property. For example:

{
    redirect: [
        {
            to: 'https://',
            status: 302, 
        },
        {
            from: '/pressRelease',
            to: '/fixedPressRelease.html',
            status: 301,
        },
    ],
}

The redirect property defines a set of redirection rules that are examined in order and the first matching redirection will be used. Each redirection rule must specify a target to property that provides a relative or absolute target URL. If a from property is provided, only those requests with a matching URL will be selected. If no from property is specified, all requests will match.

The status property defines the HTTP status to use in the redirection response.

The special redirection to: ‘https://’ will match requests using HTTP (not HTTPS) and redirect them to use the secure HTTPS protocol.

Route Authorization

If the selected route contains an authorization role property, the user must be logged in and possess the required role specified by the role property.

If the user is not logged in, or if the user does not have the requisite ability, the request will not proceed. In that case, if the route contains a redirect property, the request will receive a redirect 302 response toward the URL specified by the redirect property. If there is no such property, the request will receive a 401 Not Authorized response.

Route Patterns

A common pattern for web management applications is to require user authentication for all operations except login and logout. Such apps may have two levels of authorization, registered users and administrators.

To support such two-level access control, consider the following route list:

routes: [
    {match: '/api/admin/', role: 'admin'},
    {match: '/api/user/', role: 'user'},
    {match: '/api/'},
    {match: '/admin/', role: 'admin'},
    {match: '/user/', role: 'user'},
    {},
],

The following directory and URL structure could then be employed.

• /index.html — public home page
• /css — public stylesheets
• /js — public javascript
• /images — public images
• /login.html — login form
• /user — documents accessible by all authenticated users
• /admin — documents accessible by administrators only
• /api/admin — for action routines accessible by administrators
• /api/user — for action routines accessible by authenticated users
• /api — public action routines including login and logout actions

The {} route is used to match all other URLs and does not require authentication.

Summary

The Ioto request routine provides flexible partitioning of content for various levels of user authentication.

The next post will cover User Authentication.

Want More Now?

To learn more about EmbedThis Ioto, please read:

• Ioto Web Site
• Ioto Documentation
• Ioto Agent Download
• Builder Documentation
• Embedthis Web Site