How to create an Akka HTTP Server

The Akka HTTP modules implement a full server-side and client-side HTTP stack on top of akka-actor and akka-stream. It offers two different API with different levels of abstraction: a high-level one and a low-level one.

The high-level routing API of Akka HTTP provides a DSL to describe HTTP “routes” and how they should be handled. Each route is composed of one or more levels of Directive s that narrows down to handling one specific type of request.

The low-level Akka HTTP server API allows for handling connections or individual requests by accepting HttpRequestobjects and answering them by producing HttpResponse objects.

Adding the Akka-HTTP dependency

Akka HTTP is provided in a separate JAR file, to use it you should include the following dependency in your build.sbt file

"com.typesafe.akka"%%"akka-http"%"10.0.9"

Creating Server basic structure

First we add an Scala file to our project and create an object that extends from App and Directives.

Defining Routes

Now we are going to replace the example route /test with some more interesting ones.

All the routes we are going to define in our server are implemented using Akka-HTTP directives and have to be assigned to a Route type variable. This variable is the one which will be used as the first parameter of thebindAndHandle method.

The most easy way to add a new route is using the directive ‘path‘ along with a path as we saw in the example route above.

All the directives should finish with a complete method call.

val routes: Route =
path("test") {
complete("test")
}

Inside the path we can use different directives depending on the HTTP method that we want to use. Here is an example using the POST verb.

val routes: Route =
path("test") {
post {
complete("test")
}
}

If we want to add a new route we can concatenate two path directives just using the ~ symbol.

val routes: Route =
path("test") {
...
} ~
path("test2") {
...
}

Responding requests

Till now we saw how to return a text for an endpoint using the complete method and a text. But what about if we want to return JSON data? Well certainly we can do something like this:

Dealing with input data in request body

One common thing when we work with HTTP requests is to get information from the request body. This information has to be converted into an Scala data type in order to be able to work with it in our Akka HTTP Server. To do that we could use the entity(as(..)) structure.

Example:

path("test") {
post {
entity(as[String]) { param =>
...
}
}
}

In this example param contains the request body as an String.

This can be accomplished due Akka HTTP includes marshallers for some basic data types. Default marshallers are provided for simple objects like String or ByteString.

Dealing with JSON

Most of the times the request body information comes as a JSON structure and deal with that it’s a little more complex. There is no default marshaller for your own JSON data of course, so you have to define it.

There are some JSON libraries which can help but the most common library for these cases is the spay-json library. And here we are going to use this library to define our own marshaller.

First of all we have to define a case class with all the parameters that we are going to receive in the request JSON body.

So, for example, if our JSON data is something like:

{
names: ['jhon', 'freddy', 'kurt'],
id: 10
}

We should define a case class like this:

case class TestAPIParams(names: List[String], id: Int)

But after defining the right case class we have to define the marshaller.

To do that, we have to define a trait extending from prayJsonSupport and DefaultJsonProtocol. Inside this trait we have to define and implicit using jsonFormatX where X is the amount of parameters we have. In our case we should define the trait as follows:

Final comments

It may seem a little difficult to develop a server over Akka HTTP from scratch and certainly there are complex things in the library. However following these steps it’s easy to start and have the basic server structure and functionality quite soon. Then it’s only hard work and read the documentation. Luckily Akka HTTP has a very complete and clear official documentation, fully of examples.