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 String
s:
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