Author your first Akka service

This guide will walk you through the process of setting up your development environment, generating a project, and implementing a simple "Hello World!" REST service. By the end, you will have a functional HTTP endpoint built with the Akka SDK running locally.

Overview

The Akka SDK comes with Maven support that enables you to get started quickly. In this guide, you will:

Use the Akka Maven archetype to generate a skeleton project that follows the recommended onion architecture.
Understand how to use the Akka Maven parent POM to define dependencies and run your application locally.

If you’d rather skip past this and want to review an already completed application see the Shopping cart quickstart.

Prerequisites

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

Generate and build the skeleton 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 OS.

In IntelliJ, you can skip the command line. Open the IDE, select File > New > Project, and click to activate Create from archetype. Use the UI to locate the archetype and fill in the blanks.

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.0-b3221ba

Windows 10+

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

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.
Expand directory src/main/java/com/example/api and open the 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!");
  }
}

Basics

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.

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 complex

Endpoints provide the common capabilities you would expect for creating REST services. Here are a few more:

Path parameters

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

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.

Path parameter can be of types String, int, long, boolean, float, double, short and char as well as their java.lang class counterparts.

If you add this code above to HelloWorldEndpoint.java and restart the service, you can now curl these commands:

curl localhost:9000/hello/hello/Bob

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

Request body

To accept an HTTP JSON body, specify a parameter that is a Java record.

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

You can now call these commands as well

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

Response body

To return response with JSON, the return value can be a record that gets serialized as JSON:

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

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

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.