Routes

A Route is the set of a URL's path parts (i.e. the parts separated by /) and its query string pairs. It may have zero or more parameters, where the type of each parameter can be written to and parsed from a String. A path part is either a static String or a parameter, while a query string pair is a tuple of a String key and a parameter.

Building routes

The most basic route is the root URL, /.

import routing._

val home = root(Method.GET)
// home: Route[GET, Unit] = /

More complex routes can be built using the provided DSL.

Building the path

Static path parts can be specified as Strings:

Method.GET / "part1" / "part2"
// res0: Route[GET, Unit] = /part1/part2

Path parameters can be specified by passing a type and a String key to the pathVar method:

val edit = Method.GET / "edit" / pathVar[Int]("id")
// edit: Route[GET, Int] = /edit/<id: Int>
val hello = Method.GET / "hello" / pathVar[String]("name")
// hello: Route[GET, String] = /hello/<name: String>

For a parameter of type T, you must have implicit routing.util.Show[T] and routing.extractor.PathExtractor[T] instances defined. Instances for String, Int, Long, Boolean, and UUID are provided.

Building the query string

Query parameters can be specified by passing a String key and a type parameter to the queryParam method:

val test = Method.GET / "path" :? queryParam[Boolean]("key1") & queryParam[String]("key2")
// test: Route[GET, Tuple2[Boolean, String]] = /path?<key1: Boolean>&<key2: String>

For a parameter of type T, you must have implicit routing.util.Show[T] and routing.extractor.QueryExtractor[T] instances defined.

Optional query parameters

Query parameters with optional values, i.e. ones that may appear in the URL with or without a value, can be specified using the optionalQueryParam method:

val routeWithQueryParam = Method.GET / "path" :? optionalQueryParam[String]("key")
// routeWithQueryParam: Route[GET, Option[String]] = /path?<key: Option[String]>
routeWithQueryParam(Some("value"))
// res1: Call = /path?key=value
routeWithQueryParam(None)
// res2: Call = /path

Multi query parameters

Similarly, query parameters that may apperar in the URL zero or more times can be specified using the multiQueryParam method:

val routeWithMultiParam = Method.GET / "path" :? multiQueryParam[Int]("id")
// routeWithMultiParam: Route[GET, List[Int]] = /path?<id: List[Int]>
routeWithMultiParam(Nil)
// res3: Call = /path
routeWithMultiParam(List(1, 2))
// res4: Call = /path?id=1&id=2
← InstallationRouting →