Author: Andres Gazzoli

When we create a Web Server that should run over HTTPS we need some server certificate. If the Web Server will be exposed to internet we should buy a certificate signed by a well-known authority but if we are coding a Web Server for some internal or private use we can create our Server Certificate and sign it by ourselves.

All the certificates had to be signed by another certificate. This second certificate have to belong to a Certificate Authority (CA) in which all the clients that will receive the first certificate should trust.

But as I said before, If the clients that will use our Web Server are also our own clients we can specify that the client should trust in any CA Certificate we want.
So we can create our own CA Certificate to later signed any Server Certificate we want to use in a Web Server.

We are going to use openssl for creating the certificates.

CA Certificate

The first step is to create our own CA Certificate. To do that we should run the following commands in a terminal.

For generating the Private Key for the CA Certificate.

> openssl genrsa -des3 -out myOwnCA.key 2048

Passphrase: Whatever you want. For example ‘myca’.

For generating the CA Certificate (also know as Public Key) to later signed the Server Certificate.

When we create a certificate openssl asks us some information. We should complete at least Common Name. We can use the default values for the rest of the fields just entering a dot ‘.’

I usually completes 3 fields and for the sake of the example we can set:
1) Country Name as ‘US’
2) Organization Name as ‘My Organization’
3) Common Name with ‘MyOwnCA’

Server Certificate

Once we created the CA Certificate we have to proceed to create the Server Certificate. To do that we should run the following commands in a terminal.

For generating a Private Key for the Server Certificate. This step is similar to what we did for the CA Certificate.

> openssl genrsa -des3 -out server.key 2048

Passphrase: Whatever you want. For example: ‘server’.

For generating a Server Certificate Sign Request with the Server Private Key. Now, we don’t create the Server Certificate, we create a Server Certificate Sign Request. This request is the one we should send to some Certificate Authority for signing if we pay for that.

> openssl req -new -key server.key -out server.csr

Passphrase: What you put in the previous step.

Here again openssl asks us some information. The most important one is ‘Common Name’. We have to enter there the IP, or host name. For example: ‘localhost’. Remember that we can complete the rest of the fields or just entering a dot for the default values.

Once we have the Server Certificate Sign Request (server.csr) we should sign this request with the CA Certificate in order to get the Server Certificate Signed by our own CA.

For generating the Server Certificate we have to sign the Server Certificate Sign Request with the CA Certificate.

I have been using Swagger pages in Scala Maven project without any problem for a long time. Recently, I had to add a Swagger page to a Scala Sbt project and I faced with an unexpected problem. Besides I did the same as always I found myself struggling with some weird problem with the javax.ws.rs-api library used by Swagger.

When Sbt tries to resolve the javax.ws.rs-api dependency a weird ${packaging.type} shows up instead of the expecting jar.

I tried to compile the same code using Maven and I everything worked as expected. So I started looking in the internet about the problem and I found that this is known problem with some dependency libraries in Sbt. Basically, Sbt doesn’t handle the ${packaging.type} variable. For more information see: https://github.com/sbt/sbt/issues/3618

There are several workarounds but the one I like is to create an Sbt AutoPlugin for setting the jar package type in the build settings.

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.