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
Directives create Routes. To understand how directives work it is helpful to contrast them with the “primitive” way of creating routes.
Routes effectively are simply highly specialised functions that take a RequestContext
and eventually complete
it, which could (and often should) happen asynchronously.
Since Route
is just a type alias for a function type Route
instances can be written in any way in which function instances can be written, e.g. as a function literal:
val route: Route = { ctx => ctx.complete("yeah") }
or shorter:
val route: Route = _.complete("yeah")
With the complete directive this becomes even shorter:
These three ways of writing this Route
are fully equivalent, the created route
will behave identically in all cases.
Let’s look at a slightly more complicated example to highlight one important point in particular. Consider these two routes:
val a: Route = {
println("MARK")
ctx => ctx.complete("yeah")
}
val b: Route = { ctx =>
println("MARK")
ctx.complete("yeah")
}
The difference between a
and b
is when the println
statement is executed. In the case of a
it is executed once, when the route is constructed, whereas in the case of b
it is executed every time the route is run.
Using the complete directive the same effects are achieved like this:
val a = {
println("MARK")
complete("yeah")
}
val b = complete {
println("MARK")
"yeah"
}
This works because the argument to the complete directive is evaluated by-name, i.e. it is re-evaluated every time the produced route is run.
Let’s take things one step further:
val route: Route = { ctx =>
if (ctx.request.method == HttpMethods.GET)
ctx.complete("Received GET")
else
ctx.complete("Received something else")
}
Using the get and complete directives we can write this route like this:
val route =
concat(
get {
complete("Received GET")
},
complete("Received something else")
)
Again, the produced routes will behave identically in all cases.
Note that, if you wish, you can also mix the two styles of route creation:
val route =
concat(
get { ctx =>
ctx.complete("Received GET")
},
complete("Received something else")
)
Here, the inner route of the get directive is written as an explicit function literal.
However, as you can see from these examples, building routes with directives rather than “manually” results in code that is a lot more concise and as such more readable and maintainable. In addition it provides for better composability (as you will see in the coming sections). So, when using Akka HTTP’s Routing DSL you should almost never have to fall back to creating routes via Route
function literals that directly manipulate the RequestContext.
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:
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:
- Scala
-
source
val route: Route = path("order" / IntNumber) { id => concat( get { complete { "Received GET request for order " + id } }, put { complete { "Received PUT request for order " + id } } ) }
- Java
Here the get
and put
directives are chained together with the concat
combinator to form a higher-level route that serves as the inner route of the path
directive. Let’s rewrite it in the following way:
- Scala
-
source
def innerRoute(id: Int): Route = concat( get { complete { "Received GET request for order " + id } }, put { complete { "Received PUT request for order " + id } } ) val route: Route = path("order" / IntNumber) { id => innerRoute(id) }
- Java
What you can’t see from this snippet is that directives are not implemented as simple methods but rather as stand-alone objects of type Directive
. This gives you more flexibility when composing directives. For example you can also use the |
operator (or the or
method) on directives. Here is yet another way to write the example:
- Scala
-
source
val route = path("order" / IntNumber) { id => (get | put) { ctx => ctx.complete(s"Received ${ctx.request.method.name} request for order $id") } }
- Java
Or better (without dropping down to writing an explicit Route
function manually):
sourceval route =
path("order" / IntNumber) { id =>
(get | put) {
extractMethod { m =>
complete(s"Received ${m.name} request for order $id")
}
}
}
If you have a larger route structure where the (get | put)
snippet appears several times you could also factor it out like this:
sourceval getOrPut = get | put
val route =
path("order" / IntNumber) { id =>
getOrPut {
extractMethod { m =>
complete(s"Received ${m.name} request for order $id")
}
}
}
Note that, because getOrPut
doesn’t take any parameters, it can be a val
here.
As an alternative to nesting you can also use the &
operator (or the and
method):
sourceval getOrPut = get | put
val route =
(path("order" / IntNumber) & getOrPut & extractMethod) { (id, m) =>
complete(s"Received ${m.name} request for order $id")
}
Here you can see that, when directives producing extractions are combined with &
, the resulting “super-directive” simply extracts the concatenation of its sub-extractions.
And once again, you can factor things out if you want, thereby pushing the “factoring out” of directive configurations to its extreme:
sourceval orderGetOrPutWithMethod =
path("order" / IntNumber) & (get | put) & extractMethod
val route =
orderGetOrPutWithMethod { (id, m) =>
complete(s"Received ${m.name} request for order $id")
}
This type of combining directives with the |
and &
operators as well as “saving” more complex directive configurations as a val
works across the board, with all directives taking inner routes.
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 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.
Gotcha: forgetting the ~
(tilde) character in between directives can result in perfectly valid Scala code that compiles but does not work as expected. What would be intended as a single expression would actually be multiple expressions, and only the final one would be used as the result of the parent directive. Because of this, the recommended way to compose routes is with the the concat
combinator.
Alternatively we can combine directives using the ~
operator where we chain them together instead of passing each directive as a separate argument. Let’s take a look at the usage of this combinator:
sourcedef innerRoute(id: Int): Route =
get {
complete {
"Received GET request for order " + id
}
} ~
put {
complete {
"Received PUT request for order " + id
}
}
val route: Route = path("order" / IntNumber) { id => innerRoute(id) }
Type Safety of Directives
When you combine directives with the |
and &
operators the routing DSL makes sure that all extractions work as expected and logical constraints are enforced at compile-time.
For example you cannot |
a directive producing an extraction with one that doesn’t:
Also the number of extractions and their types have to match up:
- Scala
-
val route = path("order" / IntNumber) | path("order" / DoubleNumber) // doesn't compile val route = path("order" / IntNumber) | parameter("order".as[Int]) // ok
- Java
When you combine directives producing extractions with the &
operator all extractions will be properly gathered up:
- Scala
-
val order = path("order" / IntNumber) & parameters("oem", "expired".optional) val route = order { (orderId, oem, expired) => ... }
- Java
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.
Automatic Tuple extraction (flattening)
Convenient Scala DSL syntax described in Basics, and Composing Directives are made possible by Tuple extraction internally. Let’s see how this works with examples.
val futureOfInt: Future[Int] = Future.successful(1)
val route =
path("success") {
onSuccess(futureOfInt) { //: Directive[Tuple1[Int]]
i => complete("Future was completed.")
}
}
Looking at the above code, onSuccess(futureOfInt)
returns a Directive1[Int] = Directive[Tuple1[Int]]
.
val futureOfTuple2: Future[Tuple2[Int,Int]] = Future.successful( (1,2) )
val route =
path("success") {
onSuccess(futureOfTuple2) { //: Directive[Tuple2[Int,Int]]
(i, j) => complete("Future was completed.")
}
}
Similarly, onSuccess(futureOfTuple2)
returns a Directive1[Tuple2[Int,Int]] = Directive[Tuple1[Tuple2[Int,Int]]]
, but this will be automatically converted to Directive[Tuple2[Int,Int]]
to avoid nested Tuples.
val futureOfUnit: Future[Unit] = Future.successful( () )
val route =
path("success") {
onSuccess(futureOfUnit) { //: Directive0
complete("Future was completed.")
}
}
If the future returns Future[Unit]
, it is a bit special case as it results in Directive0
. Looking at the above code, onSuccess(futureOfUnit)
returns a Directive1[Unit] = Directive[Tuple1[Unit]]
. However, the DSL interprets Unit
as Tuple0
, and automatically converts the result to Directive[Unit] = Directive0
,