Understanding the basics of Akka HTTP

First of all, Akka http is not a framework, it’s not a skeleton to build your application or service upon. It is instead a suite of libraries that allow you to create a REST / HTTP interface to connect to your application.

If you’re searching for a framework to build your applications on you should try instead Play framework or Lagom.

The main features of Akka are:

  • High perfomance.
  • It’s based in Akka streams.
  • Lightweight.
  • Flexibility.
  • Easily testable.
  • It supports extensions to expand the functionality.

Akka http is the successor for spray or a spray 2.0. The main change is that akka http offers an API based on streams and spray offers an API based on actor messaging.

Akka http has several modules:

  • Akka-http. Higher-level functionality, this is the recommended way to write HTTP servers with Akka HTTP
  • Akka-http-core. Low-level, server- and client-side implementation of HTTP. This offers more flexibility and you can choose this low level if you have trouble achieving something with a high-level API.
  • Akka-http-testKit. A set of utilities for verifying server-side service implementations.
  • Akka-http-jackson. Is used to (de)serialise custom types from/to JSON with jackson.

Akka http can be implemented in Java or Scala. Below is a basic example based on official documentation. We’ll use this to create a server that accepts get and post requests and we’ll use Java 8 and maven.

First of all, we need to import the necessary libraries and add them to pom.xml of our project:

<dependency>
<groupId>com.typesafe.akka</groupId>
<artifactId>akka-http_2.12</artifactId>
<version>10.1.5</version>
</dependency>
<dependency>
<groupId>com.typesafe.akka</groupId>
<artifactId>akka-stream_2.12</artifactId>
<version>2.5.12</version>
</dependency>
public class BasicExample extends AllDirectives {

public static void main(String[] args) throws Exception {

ActorSystem system = ActorSystem.create("routes");
final Http http = Http.get(system);
final ActorMaterializer materializer = ActorMaterializer.create(system);
BasicExample app = new BasicExample();
final Flow<HttpRequest, HttpResponse, NotUsed> routeFlow = 
app.createRoute().flow(system, materializer);
final CompletionStage<ServerBinding> binding =
http.bindAndHandle(routeFlow, ConnectHttp.toHost("localhost", 8080),
materializer);
System.in.read();
binding.thenCompose(ServerBinding::unbind)
.thenAccept(unbound -> system.terminate());
}

private Route createRoute() {
return route(
path("hello", () ->
get(() ->
complete("<h1>Get request with akka-http</h1>")),
post(() ->
complete("<h1>Post request with akka-http</h1>"))
));
}
}

Now, let’s explain the code shown above:

Akka HTTP uses akka actors for handling concurrent requests. So, first of all we have to create an akka actor system.

ActorSystem system = ActorSystem.create("routes");

In Akka http, actors will be used for handling request and response flows. So we should use ActorMaterializer here.

final ActorMaterializer materializer = ActorMaterializer.create(system);

The next important stage is to create the route. Akka http provides a very flexible DSL to define the endpoints. If you want to read more about it, you can take a look at the Akka http official documentation.

In this example, we have the request path “hello” with a directive to accept “get” and another to “post” requests.

private Route createRoute() {
return route(
path("hello", () ->
get(() ->
complete("<h1>Get request with akka-http</h1>")),
post(() ->
complete("<h1>Post request with akka-http</h1>"))
));
}

At this point we have created a very simple http server in “http://localhost:8080/hello” that accepts get and post requests and generates a response with a string literal, sent as HTTP OK. As we see in this basic example it’s very easy to implement a REST / HTTP interface to your project.

For more information you can visit the official page of the project.