Routes

A route is a URL path you want your application to respond to. You can have as many routes as you want.

A route can be as simple as:

/users/tom

A Micro application responds to a route using a handler, such as get.

get('/users/tom', function (request, response, args) {
    response.ok('text/html');
    return 'hello, tom';
});

The application will now respond to /users/tom.

Named Parameters

Routes can include placeholders called named parameters.

This allows your application to respond to routes based on their structure rather than just their content. A named parameter starts with a colon :.

get('/users/:name', function (request, response, args) {
    response.ok('text/html');
    return 'hello, ' + args.name;
});

The URL /users/tom still works, however you can now also call /users/richard too.

Placeholders can be named with any characters, except a forward slash. You can override this, see Validating Named and Postional Parameters below.

Positional Parameters

Alternatively to named parameters, you can create routes containing placeholders with an asterisk *.

The matched values are then passed to your handler as parameters.

get('/users/*/*', function (request, response, firstname, surname) {
    response.ok('text/html');
    return 'hello, ' + firstname + ' ' + surname;
});

The route above would be called when you visit /users/tom/yandell.

You can't mix named parameters and positional parameters in the same route.

Validating Named and Positional Parameters

In order to restrict the values that will be accepted by a route, a placeholder can be followed by a regular expression fragement contained in brackets.

get('/users/:name(\\w+)', function (request, response, args) {
    response.ok('text/html');
    return 'hello, ' + firstname + ' ' + surname;
});

This route will match /users/tom, but won't match a placeholder containing non-alphanumeric characters such as /users/$-;.

As the regular expression is specified as part of a string rather than as a regular expression literal, backslashes will have to be in pairs as they would for the parameter to a new RegExp.

This works for both named and positional placeholders (e.g. /hello/*(\\w+)).

RegExp Routes

If the first parameter to get, post, etc. is a regular expression, the corresponding action will be invoked when the regular expression matches the path in the http request. Any captures in the regular expression are passed as arguments to the action callback. For example:

get(/^\/hello\/(\w+)$/, function (request, response, name) {
    response.ok('text/html');
    return 'hello, ' + name;
});

This behaves the same as for the previous examples.

Function Routes

If you've got really complicated requirements for routing, you can pass a function as the route. The function is passed the request path and its invocant (the value of "this" within the function) is the request. The function should return an containing zero or more arguments for the action callback if the route matches. For example:

get(function (path) {
    if (path === '/foo' && this.queryString === '?a=1') {
        return ['bar'];
    }
}, function (request, response, baz) {
    // baz contains 'bar' here
});

Although this feature is supported, it isn't really recommended as it makes the code less readable/maintainable. The recommended practise is to use one of the other routes and put non-path based checks into the action callback, moving onto the next route by returning:

get('/foo', function (request, response) {
    if (this.queryString !== '?a=1') {
        return;
    }
    // ...
})