Author your first Akka service

Introduction

In this guide, you will:

Set up your development environment.
Generate a simple project from a template that follows the recommended onion architecture.
Explore a basic HTTP Endpoint that responds with "Hello World!"
Add path parameters, a request body and a response body to the Endpoint.
Run your service locally.
Explore the local console to observe your running service.

Prerequisites

Java 21, we recommend Eclipse Adoptium
Apache Maven version 3.9 or later
curl command-line tool

Generate and build the project

The Maven archetype template prompts you to specify the project’s group ID, name and version interactively. Run it using the commands shown for your operating system.

If you are using IntelliJ, you can skip the command line entirely. Simply open the IDE and follow these steps:

Go to File > New > Project.
Select Maven Archetype from the list of Generators.
Fill out the project details:
- Name: Enter the desired project name, such as helloworld.
- Location: Specify the directory where you want the project to be created.
- JDK: Select Java 21 or a later version.
Under Catalog, ensure "Maven Central" is selected.
In the Archetype section, click the dropdown and select io.akka:akka-javasdk-archetype.
Set the Version to 3.0.2.
Click Create.

IntelliJ will handle the project generation and setup for you, allowing you to begin development immediately.

Follow these steps to generate and build your project:

From a command line, create a new Maven project from the Akka archetype in a convenient location:

Linux or macOS

mvn archetype:generate \
  -DarchetypeGroupId=io.akka \
  -DarchetypeArtifactId=akka-javasdk-archetype \
  -DarchetypeVersion=3.0.2

Windows 10+

mvn archetype:generate ^
  -DarchetypeGroupId=io.akka ^
  -DarchetypeArtifactId=akka-javasdk-archetype ^
  -DarchetypeVersion=3.0.2

Fill in:

groupId: com.example
artifactId: helloworld
version: 1.0-SNAPSHOT
package: helloword

Navigate to the new project directory.
Open it in your preferred IDE / Editor.

Explore the HTTP Endpoint

An Endpoint is a component that creates an externally accessible API. Endpoints are how you expose your services to the outside world. Endpoints can have different protocols and, initially, support HTTP.

HTTP Endpoint components make it possible to conveniently define such APIs accepting and responding in JSON, or dropping down to lower level APIs for ultimate flexibility in what types of data is accepted and returned.

Open the src/main/java/com/example/api/HelloWorldEndpoint.java file.

The Endpoint is implemented with:

HelloWorldEndpoint.java

@Acl(allow = @Acl.Matcher(principal = Acl.Principal.INTERNET))
@HttpEndpoint("/hello")
public class HelloWorldEndpoint {

  @Get("/")
  public CompletionStage<String> helloWorld() {
    return completedStage("Hello World!");
  }
}

This Endpoint is on the path /hello and exposes an HTTP GET operation on /.

You can also see that there is an Access Control List (ACL) on this Endpoint that allows all traffic from the Internet. Without this ACL the service would be unreachable, but you can be very expressive with these ACLs.

Run locally

Start your service locally:

mvn compile exec:java

Once successfully started, any defined Endpoints become available at localhost:9000 and you will see an INFO message that the Akka Runtime has started.

Your "Hello World" service is now running.

In another shell, you can now use curl to send requests to this Endpoint.

curl localhost:9000/hello

Which will reply

Hello World!

Getting more advanced

In this section, you will modify the HTTP Endpoint to accept path parameters, a request body, and return a response body.

Add path parameters

The path can also contain one or more parameters, which are extracted and passed to the method.

Path parameters can be of type String, int, long, boolean, float, double, short or char, as well as their java.lang class counterparts.

Add path parameters to the Endpoint using the code shown below:

HelloWorldEndpoint.java

  @Get("/hello/{name}") (1)
  public String hello(String name) { (2)
    return "Hello " + name;
  }

  @Get("/hello/{name}/{age}") (3)
  public String hello(String name, int age) { (4)
    return "Hello " + name + "! You are " + age + " years old";
  }

1	Path parameter `name` in expression.
2	Method parameter named as the one in the expression
3	When there are multiple parameters
4	The method must accept all the same names in the same order as in the path expression.

Restart the service and curl these commands:

curl localhost:9000/hello/hello/Bob

curl localhost:9000/hello/hello/Bob/30

Add a request body

Modify the Endpoint to accept an HTTP JSON body using the code shown below:

HelloWorldEndpoint.java

  public record GreetingRequest(String name, int age) {} (1)

  @Post("/hello")
  public String hello(GreetingRequest greetingRequest) { (2)
    return "Hello " + greetingRequest.name + "! " +
        "You are " + greetingRequest.age + " years old";
  }

  @Post("/hello/{number}") (3)
  public String hello(int number, GreetingRequest greetingRequest) { (4)
    return number + " Hello " + greetingRequest.name + "! " +
        "You are " + greetingRequest.age + " years old";
  }

1	The record will serialized and deserialized as JSON
2	A parameter of the request body type
3	When combining request body with path variables
4	The body must come last in the parameter list

Restart the service and curl this command:

curl -i -XPOST -H "Content-Type: application/json" localhost:9000/hello/hello -d '
{"age":"30", "name":"Bob"}'

Add a response body

Modify the Endpoint to return a response body using the code shown below:

HelloWorldEndpoint.java

  public record MyResponse(String name, int age) {}

  @Get("/hello-response/{name}/{age}")
  public MyResponse helloJson(String name, int age) {
    return new MyResponse(name, age); (1)
  }

1	Returning a record that gets serialized as JSON

Restart the service and curl this command:

curl localhost:9000/hello/hello-response/Bob/30

Explore the local console

The Akka local console is a web-based tool that provides a convenient way to view and interact with your running service.

Install the Akka CLI

Starting the local console requires using the Akka CLI and Docker.

Install the Akka CLI:

In case there is any trouble with installing the CLI when following these instructions, please check Install the Akka CLI.

Linux

Download and install the latest version of akka:

curl -sL https://doc.akka.io/install-cli.sh | bash

macOS

The recommended approach to install akka on macOS, is using brew

brew install akka/brew/akka

Windows

Download the latest version of akka from https://downloads.akka.io/latest/akka_windows_amd64.zip
Extract the zip file and move akka.exe to a location on your %PATH%.

Verify that the Akka CLI has been installed successfully by running the following to list all available commands:

akka help

Start the local console

Start the local console. It will launch a Docker container:

akka local console

Pulling local console image, please wait...

Once the console is running, you will see a message like this:

- helloworld is running at: localhost:9000
-----------------------------------------------------
(use Ctrl+C to quit)

You can then access the local console in your browser at:

http://localhost:3000
Navigate to your service’s Endpoint, which will be available here.

hello world local console

This is a simple Hello World service, so there isn’t much to see here yet. However, as you build more complex services, the console will become a more valuable tool for monitoring and debugging.

Next steps

Now that you have a basic service running, it’s time to learn more about building real services in Akka. See the Shopping cart quickstart to build a more realistic application and learn how to deploy it to akka.io.