Compared with Play routes
If you have been using Play’s routes file syntax earlier, this page may help you to use the Akka HTTP routing DSL.
Conceptual differences
The most apparent difference is Play’s use of special purpose syntax implemented as an external DSL, whereas Akka HTTP routes are described in Scala source code with regular methods and values (as “embedded DSL”). Both are crafted to make the reader “grasp the code’s intention”.
The Akka HTTP DSL uses Directives to describe how incoming requests translate to functionality in the server. Play allows splitting the routes definitions in multiple routes files. The Akka HTTP DSL is very flexible and allows for composition so that different concerns can be properly split and organized as other source code would be.
Both Play and Akka HTTP choose the first matching route within the routes file/routes definition. In Play routes are listed with one route per line, in Akka HTTP multiple routes must be concatenated with the concat
method.
Side-by-side
These examples are a non-comprehensive list of how Play routes could be written in Akka HTTP. They try to mimic the structure which Play uses, to aid understanding, even though it might not be the most Akka HTTP-idiomatic notation.
Static path
For example, to exactly match incoming GET /clients/all
requests, you can define this route in Play.
GET /clients/all controllers.Clients.list()
In Akka HTTP every path segment is specified as a separate String
concatenated with the /
method .
- Scala
-
source
(get & path("clients" / "all")) { complete(Clients.list()) }
- Scala test
- Java
- Java test
Dynamic parts
If you want to define a route that retrieves a client by ID, you’ll need to add a dynamic part.
GET /clients/:id controllers.Clients.show(id: Long)
Akka HTTP uses path matchers which match certain data types and pass their data on.
- Scala
-
source
(get & path("client" / LongNumber)) { id => complete(Clients.get(id)) }
- Scala test
- Java
- Java test
Dynamic parts spanning several /
You may want to capture a dynamic part of more than one URI path segment, separated by forward slashes.
GET /files/*name controllers.Application.download(name)
The Akka HTTP directive Remaining
makes a list of the segments to be passed. (See Path Matchers for other ways to extract the path.)
- Scala
-
source
(get & path("files" / Remaining)) { name => complete(download(name)) }
- Scala test
- Java
- Java test
Access parameters
The Parameter directives give access to parameters passed on the URL.
Mandatory parameters
By default parameters are expected to be of type String
. To make Akka HTTP convert a parameter to a different type, specify an unmarshaller.
# Extract the page parameter from the query string.
# i.e. http://myserver.com/?page=index
GET / controllers.Application.show(page)
- Scala
-
source
(get & path("") & parameter("page")) { page => complete(getPage(page)) }
- Scala test
- Java
- Java test
Optional parameters
# The version parameter is optional. E.g. /api/list-all?version=3.0
GET /api/list-all controllers.Api.list(version: Option[String])
The parameter name may be decorated with .optional
to mark it as optional (for other variants see other parameter extractors).
- Scala
-
source
(get & path("api" / "list-all") & parameter("version".optional)) { version => complete(listAll(version)) }
- Scala test
- Java
- Java test
List parameters
This shows how a repeated URL parameter is captured.
# The item parameter is a list.
# E.g. /api/list-items?item=red&item=new&item=slippers
GET /api/list-items controllers.Api.listItems(item: List[String])
Decorating the parameter name with a .repeated
makes Akka HTTP pass all values of that parameter as an Iterable[String]
].
- Scala
-
source
(get & path("api" / "list-items") & parameters("item".repeated)) { items => complete(listItems(items)) }
- Scala test
- Java
- Java test