Directives

A “Directive” is a small building block used for creating arbitrarily complex route structures. Akka HTTP already pre-defines a large number of directives and you can easily construct your own:

Basics

Routes effectively are simply highly specialised functions that take a RequestContext and eventually complete it, which could (and often should) happen asynchronously.

With the complete directive this becomes even shorter:

Route route = complete("yeah");

Writing multiple routes that are tried as alternatives (in-order of definition), is as simple as using the route(route1, route2), method:

Route routes = route(
  pathSingleSlash(() ->
    getFromResource("web/calculator.html")
  ),
  path("hello", () -> complete("World!))
);

You could also simply define a “catch all” completion by providing it as the last route to attempt to match. In the example below we use the get() (one of the MethodDirectives) to match all incoming GET requests for that route, and all other requests will be routed towards the other “catch all” route, that completes the route:

Route route =
  get(
    () -> complete("Received GET")
  ).orElse(
    () -> complete("Received something else")
  )

If no route matches a given request, a default 404 Not Found response will be returned as response.

Structure

The general anatomy of a directive is as follows:

directiveName(arguments [, ...], (extractions [, ...]) -> {
  ... // inner route
})

It has a name, zero or more arguments and optionally an inner route (The RouteDirectives are special in that they are always used at the leaf-level and as such cannot have inner routes).

Additionally directives can “extract” a number of values and make them available to their inner routes as function arguments. When seen “from the outside” a directive with its inner route form an expression of type Route.

What Directives do

A directive can do one or more of the following:

• Transform the incoming RequestContext before passing it on to its inner route (i.e. modify the request)
• Filter the RequestContext according to some logic, i.e. only pass on certain requests and reject others
• Extract values from the RequestContext and make them available to its inner route as “extractions”
• Chain some logic into the RouteResult future transformation chain (i.e. modify the response or rejection)
• Complete the request

This means a Directive completely wraps the functionality of its inner route and can apply arbitrarily complex transformations, both (or either) on the request and on the response side.

Composing Directives

As you have seen from the examples presented so far the “normal” way of composing directives is nesting. Let’s take a look at this concrete example:

Route orElse() {
  return path(segment("order").slash(integerSegment()), id ->
    get(() -> complete("Received GET request for order " + id))
      .orElse(
        put(() -> complete("Recieved PUT request for order " + id)))
  );
}

Here the get and put routes are chained together with using the orElse method to form a higher-level route that serves as the inner route of the path directive. Let’s rewrite it in the following way:

Route getOrPut(Supplier<Route> inner) {
  return get(inner)
    .orElse(put(inner));
}

Route customDirective() {
  return path(segment("order").slash(integerSegment()), id ->
    getOrPut(() ->
      extractMethod(method -> complete("Received " + method + " for order " + id)))
  );
}

In this previous example, we combined the get and put directives into one composed directive and extracted it to its own method, which could be reused anywhere else in our code.

Instead of extracting the composed directives to its own method, we can also use the available anyOf combinator. The following code is equivalent to the previous one:

Route usingAnyOf() {
  return path(segment("order").slash(integerSegment()), id ->
    anyOf(this::get, this::put, () ->
      extractMethod(method -> complete("Received " + method + " for order " + id)))
  );
}

The previous example, tries to complete the route first with a GET or with a PUT if the first one was rejected.

In case you are constantly nesting the same directives several times in you code, you could factor them out in their own method and use it everywhere:

Route getWithIP(Function<RemoteAddress, Route> inner) {
  return get(() ->
      extractClientIP(address -> inner.apply(address))
  );
}

Route complexRoute() {
  return path(segment("order").slash(integerSegment()), id ->
    getWithIP(address ->
      complete("Received request for order " + id + " from IP " + address))
  );
}

Here we simple created our own combined directive that accepts GET requests, then extracts the method and completes it with an inner route that takes this HTTP method as a parameter.

Again, instead of extracting own combined directives to its own method, we can make use of the allOf combinator. The following code is equivalent to the previous one:

Route complexRouteUsingAllOf() {
  return path(segment("order").slash(integerSegment()), id ->
    allOf(this::get, this::extractClientIP, address ->
      complete("Received request for order " + id + " from IP " + address))
  );
}

In this previous example, the the inner route function provided to allOf will be called when the request is a GET and with the extracted client IP obtained from the second directive.

As you have already seen in the previous section, you can also use the route method defined in RouteDirectives as an alternative to orElse chaining. Here you can see the first example again, rewritten using route:

Route usingRoute() {
  return path(segment("order").slash(integerSegment()), id ->
    route(get(() -> complete("Received GET request for order " + id)),
          put(() -> complete("Received PUT request for order " + id)))
  );
}

The route combinator comes handy when you want to avoid nesting. Here you can see an illustrative example:

Route multipleRoutes() {
  return path(segment("order").slash(integerSegment()), id ->
    route(get(()  -> complete("Received GET request for order " + id)),
          put(()  -> complete("Received PUT request for order " + id)),
          head(() -> complete("Received HEAD request for order " + id)))
  );
}

Notice how you could adjust the indentation in these last two examples to have a more readable code.

Note that going too far with “compressing” several directives into a single one probably doesn’t result in the most readable and therefore maintainable routing code. It might even be that the very first of this series of examples, or the analogous one using route, is in fact the most readable one.

Still, the purpose of the exercise presented here is to show you how flexible directives can be and how you can use their power to define your web service behavior at the level of abstraction that is right for your application.

Type Safety of Directives

When you combine directives with anyOf and allOf methods the routing DSL makes sure that all extractions work as expected and logical constraints are enforced at compile-time.

For example you cannot call anyOf with a directive producing an extraction with one that doesn’t:

anyOf(this::get, this::extractClientIP, routeProvider) // doesn't compile

Also the number of extractions and their types have to match up:

anyOf(this::extractClientIP, this::extractMethod, routeProvider) // doesn't compile
anyOf(bindParameter(this::parameter, "foo"), bindParameter(this::parameter, "bar"), routeProvider) // ok

In this previous example we make use of the bindParameter function located in akka-http/akka.http.javadsl.common.PartialApplication. In order to be able to call anyOf, we need to convert our directive that takes 2 parameters to a function that takes only 1. In this particular case we want to use the parameter directive that takes a String and a function from String to Route, so to be able to use it in combination with anyOf, we need to bind the first parameter to foo and to bar in the second one. bindParameter(this::parameter, "foo") is equivalent to define your own function like this:

Route parameterFoo(Function<String, Route> inner) {
  return parameter("foo", inner);
}

When you combine directives producing extractions with the allOf method all extractions will be properly gathered up:

allOf(this::extractScheme, this::extractMethod, (scheme, method) -> ...) 

Directives offer a great way of constructing your web service logic from small building blocks in a plug and play fashion while maintaining DRYness and full type-safety. If the large range of Predefined Directives does not fully satisfy your needs you can also easily create Custom Directives.