Routing #

This chapter explains how to configure routing for your application. Diego provides two ways to define routes - Express-style routing and Controllers.

Express-style Routing 🚧 #

This feature is still under development and its API may change over time.

With Express-style routing, you use the HTTP mapping methods on the WebMvcApplication to create RESTful routes similar to frameworks like Express, Koa, Javalin, etc. This can be useful for small applications that may not require the ceremony of Controllers.

The following is a list of all the methods you can use to create routes:

/* Create a DELETE route. */
app.delete(String path, Handler handler);
/* Create a GET route. */
app.get(String path, Handler handler);
/* Create a PATCH route. */
app.patch(String path, Handler handler);
/* Create a POST route. */
app.post(String path, Handler handler);
/* Create a PUT route. */
app.put(String path, Handler handler);

Each route must have a path and one handler.

The path can be an exact URL pattern (e.g. /about) or contain path variables such as /users/:id.

The handler contains the logic for how to consume a request and generate a response. Routes will be matched in the order they were added.

public class IndexHander implements Router.Handler {
    public void handle(Context ctx) {
        /* Handler logic. */
    }
}

app.get("/", new IndexHandler());

The diego.web.Router.Handler interface is a functional interface with a single method that accepts an instance of Context . With that in mind, the above code can be rewritten using the more concise lambda syntax:

/* For a more Express-like experience */
app.get("/", (ctx) -> { ... })

In the example above, we created a route that will respond to an HTTP GET on the / path.

The more concise lambda style is the format that will be used throughout the documentation.

Path parameters #

You can store parameters in your route paths using the Express path parameter notation.

app.get("/users/:id/show", (ctx) -> {
    Long id = Long.parseLong(ctx.pathParameter("id")); // Get the path parameter and parse it to a Long.
    // Do stuff with the id
})

Route order #

Routes are appended to the application router in the order they were declared. With this in mind, it is a good practice to declare routes with more generalized paths further down the routing stack.

app.get("/*", (ctx) -> res.ok().send("I block everybody 😈"));
app.get("/unreachable", ctx -> { /* Cannot be reached by any GET requests. */ });

In the above example, the first route will match any GET requests being sent to this application, but because of it’s generalized path, other GET routes further down the chain will become unreachable. It would be logical to declare this route last.

Filters #

Filters come from the Jakarta Servlet Specification, and they are a way for you to intercept and process incoming requests. Filters are implementations of the diego.web.Router.RequestFilter interface.

A common use of Filters is for authorization:

app.addFilter("/admin/*", ctx -> {
    if(!ctx.user().isInRole("admin")) ctx.flash("notice", "Please log in.").redirect("/login");
})

Unlike regular routes, Filters cannot have path parameters as part of their definition; only the * character is allowed for denoting dynamic URL segments. Still, you would be able to extract path parameters if the intended route has path parameters in its URL template.

Filters can also be applied to multiple URL patterns:

app.addFilter(myFilter).setUrlPatters("/path1", "/path2", ...);

Interceptors #

This feature is being reconsidered. Use Filters for now, as they provide broader coverage of application endpoints.

Interceptors allow you to… well, intercept, requests at a given path. Once intercepted, a request can be examined and have business logic applied to it. A popular use case for interceptors is the implementation of authorization.

Interceptors can be created using the following methods:

/* Create an interceptor at a specific path. */
app.addInterceptor(String path, Interceptor interceptor);
/* Create an interceptor for all routes. */
app.addInterceptor(Interceptor interceptor);

Below is an example of a typical authorization interceptor:

app.addInterceptor("/private/*", (ctx, route) -> {
    // Check if user is authorized
    if(!userHasPermissions()) {
        ctx.unauthorized().send("You do not have permission.");
        return false;
    } else return true; // You *must* return true if you wish to pass the request to the next interceptor.
});

In the above example, any requests going to /private/{any/sub/path/} will be checked for user authorization. If the check fails, a 401 UNAUTHORIZED response is returned. Otherwise, the request is passed to the next interceptor that matches the /private/* pattern.

You can also apply an interceptor to multiple URL patterns, for example:

app.addInterceptor(myInterceptor)
    .addUrlPattern("/path1")
    .addUrlPattern("/path2");

Next: Controllers.