Reading Query Parameters in Akka HTTP

1. Overview

Akka HTTP is a module of Akka, a toolkit written in Scala to build concurrent, distributed, and asynchronous applications. It’s implemented on top of Akka Actors and Akka Streams and provides tools for building HTTP-based applications with a flexible API.

In this tutorial, we’ll learn how to read query parameters with the Akka HTTP library.

2. Setup

First, let’s add Akka HTTP dependencies to our build.sbt file:

lazy val akkaVersion = "2.8.0"
lazy val akkaHttpVersion = "10.5.0"

libraryDependencies ++= Seq(
  "com.typesafe.akka" %% "akka-actor-typed" % akkaVersion,
  "com.typesafe.akka" %% "akka-stream" % akkaVersion,
  "com.typesafe.akka" %% "akka-http" % akkaHttpVersion
)

3. Parameters Directive

In the Akka HTTP library, we can define our routing structures with Directives — blocks of code to define our HTTP structures. There are some pre-defined directives in Akka, for example, complete and get.

Let’s use the directives to build our primary endpoint:

val route =
  path("params") {
    get {
      complete(HttpEntity(ContentTypes.`text/plain(UTF-8)`, "It's working"))
    }
  }

In this code, we used the path directive to indicate the path name, and inside, we used the get directive to define our HTTP GET method. Also, with the complete directive, we can implement the logic to obtain our response.

Now, let’s use the parameters directive, which allows us to design defined query parameters in our route:

val route = path("with-parameters") {
  get {
    parameters(Symbol("page").as[String], Symbol("size").as[String]) { (page, size) =>
      complete(HttpEntity(ContentTypes.`text/plain(UTF-8)`, s"parameters passed: page=$page and size=$size"))
    }
  }
}

The parameters directive allows us to define our two query parameters – page and size, respectively – and define their type conversion.

After that, let’s execute this code and make a request to our /with-parameters endpoint, passing query parameters size=23&page=0. Let’s look at the response we received:

HTTP/1.1 200 OK
Content-Length: 37
Content-Type: text/plain; charset=UTF-8
Date: Thu, 01 Dec 2022 02:03:27 GMT
Server: akka-http/10.4.0

parameters passed: page=0 and size=23

With this response, we can conclude that our code could get the values in the query parameters and echo them in the returned text.

4. Extract Directive

We can use the pre-defined extract directive to extract any data from the request context, including the query parameters. Let’s see how the extract directive can retrieve query parameters:

path("with-extract") {
  get {
    extract(_.request.uri.query()) { params =>
      complete(HttpEntity(ContentTypes.`text/plain(UTF-8)`, s"parameters passed: page=${params.get("page").get} and size=${params.get("size").get}"))
    }
  }
}

Similarly to the parameters directive, we define the extract directive inside our get directive and get the values inside the params, which can be used to retrieve the values.

5. Conclusion

In this tutorial, we looked into some concepts in Akka HTTP and how to read query parameters using its directives.

As usual, the source code presented here is available over on GitHub.