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.