Routing

What is routing?

In Kauri, routing means the problem of mapping an incoming request to a resource class.

Routing is usually done based on the request URI, in particular its path component.

   http://kauriproject.org/documentation/tutorial.html?foo=bar&foo2=bar2
   <--> <----------------><--------------------------><---------------->
  scheme    authority              path                  query string

If you are familiar with other web-frameworks supporting configurable routing, you are probably wondering how the routing is configured in Kauri. For completeness, you should know there are multiple levels of routing (see next section), but the most interesting one is how routing is done within a module. For this, Kauri provides a standard routing infrastructure which is configured with a syntax like this:

builder.router {
    resource(uri: "/user/{name}", ofClass: "mystuff.UserResource")
    resource(uri: "/order/{orderId}", ofClass: "mystuff.OrderResource")
}

The syntax of this file is Groovy using the Groovy Builder convention. The uri patterns are defined using URI template syntax, in which the parts in brackets {} represent wildcards.

This is a very basic example, there are lots of other possibilities described later on.

The full picture: how a request is routed

To refresh your memory, a Kauri setup consists of a number of modules which can provide restservices. These restservices are mounted on a certain path on a certain virtual host. From this sentence, we can already two levels of routing which happen:

1. an incoming request is routed based on the virtual hosts configuration. If you have not configured any virtual hosts, you don't need to worry about this item, every request will go to the one and only default virtual host.

2. next, the request is routed to a certain restservice based on the path on which the restservice is mounted

Once the request arrives at the restservice, it is up to the restservice to decide how the request should be handled further.

Power users will appreciate the fact that they can implement any sort of behavior as desired. However, this is rather low-level work and quickly recurring patterns will appear, therefore Kauri provides a standard routing infrastructure (= the one configured with the Groovy syntax) which should suffice for just about all routing requirements.