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
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.
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:
@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:
@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:
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:
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 brewbrew 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:
-
Navigate to your service’s Endpoint, which will be available here.
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.