Overview of Akka HTTP and Its Features

What is Akka HTTP?

Akka HTTP is a lightweight, performant library for building HTTP-based applications using the Akka toolkit. It is designed to be both simple and powerful, allowing you to create robust web services and APIs with minimal effort. Akka HTTP is part of the Akka ecosystem, which also includes Akka Actors and Akka Streams, and it leverages the powerful concurrency model of Akka.

Key Features of Akka HTTP

1. Routing DSL: Akka HTTP provides a Domain-Specific Language (DSL) for defining routes in a declarative and expressive manner.
2. Streaming Support: It integrates seamlessly with Akka Streams, allowing you to handle large volumes of data efficiently.
3. Customizable Directives: Directives are reusable building blocks for defining request handling logic.
4. Flexible and Scalable: Designed to be used in a wide range of applications, from simple services to complex microservices architectures.
5. Integration with Akka: Provides out-of-the-box integration with Akka Actors and Akka Streams for building concurrent and reactive systems.

Setting Up a Scala Project with Akka HTTP

Step 1: Create a New Scala Project

You can use sbt (Simple Build Tool) to create and manage your Scala project. To get started, create a new directory for your project and initialize it with sbt.

mkdir akka-http-demo
cd akka-http-demo
sbt new scala/scala-seed.g8

This command will set up a basic Scala project structure.

Step 2: Add Akka HTTP Dependencies

Open the build.sbt file in your project directory and add the Akka HTTP and Akka Actor dependencies. You can also add Akka Streams if you plan to use streaming features.

name := "akka-http-demo"

version := "0.1"

scalaVersion := "2.13.10"

libraryDependencies ++= Seq(
  "com.typesafe.akka" %% "akka-http" % "10.3.10",
  "com.typesafe.akka" %% "akka-stream" % "2.6.20",
  "com.typesafe.akka" %% "akka-actor" % "2.6.20"
)

After updating the dependencies, reload sbt to fetch the new libraries:

sbt reload

Step 3: Set Up the Project Structure

Create a directory structure for your project. You will typically have a main source directory and a test source directory.

mkdir -p src/main/scala
mkdir -p src/test/scala

Building and Testing a Simple RESTful API

Step 1: Create the API Server

Create a new Scala file in the src/main/scala directory, e.g., ApiServer.scala, and set up a basic Akka HTTP server.

import akka.actor.ActorSystem
import akka.http.scaladsl.Http
import akka.http.scaladsl.server.Directives._
import akka.http.scaladsl.server.Route
import akka.stream.ActorMaterializer

import scala.io.StdIn

object ApiServer {
  def main(args: Array[String]): Unit = {
    implicit val system: ActorSystem = ActorSystem("my-system")
    implicit val materializer: ActorMaterializer = ActorMaterializer()
    import system.dispatcher

    val route: Route =
      path("hello") {
        get {
          complete("Hello, world!")
        }
      }

    val bindingFuture = Http().bindAndHandle(route, "localhost", 8080)

    println(s"Server online at http://localhost:8080/")
    StdIn.readLine() // Let it run until user presses return
    bindingFuture
      .flatMap(_.unbind())
      .onComplete(_ => system.terminate())
  }
}

In this example:

• ActorSystem: Manages the lifecycle of actors and supervises their execution.
• ActorMaterializer: Materializes Akka Streams and manages their execution.
• Route: Defines a simple route that responds with "Hello, world!" when accessed via a GET request to /hello.
• Http().bindAndHandle: Binds the route to the specified address and port.

Step 2: Run the API Server

Run the server using sbt:

sbt run

Open your browser or use a tool like curl to test the endpoint:

curl http://localhost:8080/hello

You should receive a response with "Hello, world!".

Step 3: Create More Complex Routes

Enhance your API by adding more routes and handling different HTTP methods. Create a file named ApiRoutes.scala in the src/main/scala directory:

import akka.http.scaladsl.server.Directives._
import akka.http.scaladsl.server.Route

object ApiRoutes {
  val route: Route =
    pathPrefix("api") {
      concat(
        path("hello") {
          get {
            complete("Hello, world!")
          }
        },
        path("items") {
          get {
            complete("List of items")
          }
        },
        path("items" / Segment) { itemId =>
          get {
            complete(s"Item details for $itemId")
          }
        }
      )
    }
}

In this example:

• pathPrefix: Defines a common prefix for the routes.
• concat: Combines multiple routes.
• Segment: Captures a path segment (e.g., item ID).

Update ApiServer.scala to use the new routes:

import akka.actor.ActorSystem
import akka.http.scaladsl.Http
import akka.stream.ActorMaterializer

import scala.io.StdIn

object ApiServer {
  def main(args: Array[String]): Unit = {
    implicit val system: ActorSystem = ActorSystem("my-system")
    implicit val materializer: ActorMaterializer = ActorMaterializer()
    import system.dispatcher

    val route = ApiRoutes.route

    val bindingFuture = Http().bindAndHandle(route, "localhost", 8080)

    println(s"Server online at http://localhost:8080/")
    StdIn.readLine() // Let it run until user presses return
    bindingFuture
      .flatMap(_.unbind())
      .onComplete(_ => system.terminate())
  }
}

Step 4: Write Tests for Your API

To ensure your API works as expected, write tests using Akka HTTP’s testkit. Create a file named ApiServerSpec.scala in the src/test/scala directory:

import akka.actor.ActorSystem
import akka.http.scaladsl.testkit.ScalatestRouteTest
import akka.http.scaladsl.model.StatusCodes
import org.scalatest.matchers.should.Matchers
import org.scalatest.wordspec.AnyWordSpec

class ApiServerSpec extends AnyWordSpec with Matchers with ScalatestRouteTest {
  implicit val system: ActorSystem = ActorSystem("test-system")

  "The API" should {
    "return a greeting on GET /hello" in {
      Get("/api/hello") ~> ApiRoutes.route ~> check {
        status shouldBe StatusCodes.OK
        responseAs[String] shouldEqual "Hello, world!"
      }
    }

    "return a list of items on GET /items" in {
      Get("/api/items") ~> ApiRoutes.route ~> check {
        status shouldBe StatusCodes.OK
        responseAs[String] shouldEqual "List of items"
      }
    }

    "return item details on GET /items/:id" in {
      Get("/api/items/42") ~> ApiRoutes.route ~> check {
        status shouldBe StatusCodes.OK
        responseAs[String] shouldEqual "Item details for 42"
      }
    }
  }
}

In this test:

• ScalatestRouteTest: Provides tools for testing HTTP routes.
• check: Verifies the HTTP response status and body.

Handling Requests, Responses, and Routing

Handling Requests

Akka HTTP provides a range of directives for extracting data from requests, such as parameter, headerValueByName, and entity.

Example: Extracting Query Parameters:

path("search") {
  get {
    parameter("q") { query =>
      complete(s"Search results for: $query")
    }
  }
}

Handling Responses

You can customize responses using various directives and responses objects.

Example: Custom Response with JSON:

import akka.http.scaladsl.model.HttpEntity
import akka.http.scaladsl.model.ContentTypes
import akka.http.scaladsl.marshallers.sprayjson.SprayJsonSupport._
import spray.json.DefaultJsonProtocol._

case class Item(id: Int, name: String)

object ItemJsonProtocol extends DefaultJsonProtocol {
  implicit val itemFormat = jsonFormat2(Item)
}

import ItemJsonProtocol._

path("items" / IntNumber) { id =>
  get {
    val item = Item(id, s"Item $id")
    complete(HttpEntity(ContentTypes.`application/json`, item.toJson.prettyPrint))
  }
}

Routing

Akka HTTP uses a powerful routing DSL to define how requests are handled.

Example: Routing with Path Prefix and Conditional Logic:

pathPrefix("api") {
  path("status") {
    get {
      complete("API is running")
    }
  } ~
  path("ping") {
    get {
      complete("pong")
    }
  }
}

Here, pathPrefix groups routes under the /api prefix, and ~ combines different route definitions.

Conclusion

Building RESTful APIs with Scala and Akka HTTP offers a powerful and flexible approach to web service development. In this guide, we covered:

• An overview of Akka HTTP and its key features.
• Setting up a Scala project with Akka HTTP.
• Building and testing a simple RESTful API.
• Handling requests, responses, and routing.

With this foundation, you’re equipped to build and expand your own APIs using Akka HTTP, leverage its powerful features for handling complex routing and data processing, and create robust and scalable web services. Continue to explore Akka HTTP’s documentation and experiment with more advanced features as you develop your API skills. Happy coding!