How to Create Your First Micronaut API in 2026

Introduction

Micronaut is a modern JVM framework designed for microservices and serverless apps. Unlike Spring Boot, it compiles ahead-of-time (AOT), slashing memory usage and startup time—ideal for Kubernetes or cloud functions. In 2026, with Java 21+, Micronaut shines in scalable REST APIs, GraphQL, and gRPC.

This beginner tutorial walks you step-by-step through building a complete REST API: a GET endpoint to list users, a POST to add them, with an injected business service. You'll master native dependency injection, reactive annotations, and hot-reload. At the end, your app will be production-ready and testable in minutes. Why it matters: Legacy frameworks like Spring are heavyweight; Micronaut starts in <100ms and uses <50MB RAM. Perfect for Java devs boosting performance without a full rewrite.

Prerequisites

Java 17 or higher (ideally 21+ for virtual threads)
SDKMAN installed for managing CLI tools
An IDE like IntelliJ IDEA Community (free) with the Micronaut plugin
Basic Java and HTTP (REST) knowledge
Terminal (bash/zsh on macOS/Linux, Git Bash on Windows)

Install Micronaut CLI

terminal-install.sh

curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk version
sdk install java 21.0.4-tem
sdk install micronaut
mn --version

This script installs SDKMAN, Java 21, and Micronaut CLI (version 4+ in 2026). Run it once. Verify with mn --version: you should see 4.x.x. Skip manual installs for automatic updates.

Create the Base Project

We'll use the CLI to generate an HTTP-ready skeleton. It creates a Gradle project with everything needed: build.gradle, Application.java, and hot-reload via DevTools.

Generate the Application

terminal-create.sh

mn create-app ma-premiere-api --features http,graalvm --build=gradle --lang=java
cd ma-premiere-api
gradle build

Creates a project with HTTP and GraalVM support (for native images). --lang=java ensures pure Java. gradle build compiles and tests. The src/main folder is ready. Gotcha: don't forget cd before building.

Create the API Controller

src/main/java/example/UserController.java

package example;

import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.annotation.Post;
import io.micronaut.http.annotation.Body;

import java.util.List;
import java.util.ArrayList;

@Controller("/users")
public class UserController {

    private List<String> users = new ArrayList<>();

    @Get
    public List<String> list() {
        return users;
    }

    @Post
    public String add(@Body String name) {
        users.add(name);
        return "User " + name + " added";
    }
}

This controller exposes /users (GET lists, POST adds). Micronaut annotations handle routing and auto-binding. In-memory list for simplicity. Gotcha: always specify the package; test without a DB first.

Add a Business Service

To decouple logic, we'll inject a service with @Inject. This showcases Micronaut's zero-config DI, no XML or scanning required.

Implement the UserService

src/main/java/example/UserService.java

package example;

import jakarta.inject.Singleton;

import java.util.List;
import java.util.ArrayList;

@Singleton
public class UserService {

    private List<String> users = new ArrayList<>();

    public List<String> list() {
        return new ArrayList<>(users); // Defensive copy
    }

    public String add(String name) {
        users.add(name);
        return "User " + name + " added";
    }
}

@Singleton auto-registers the bean. Simple methods with defensive copying for thread-safety. In production, swap for a DB like PostgreSQL. Benefit: injectable anywhere without config.

Update the Controller with Injection

src/main/java/example/UserController.java

package example;

import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.annotation.Post;
import io.micronaut.http.annotation.Body;

import jakarta.inject.Inject;

import java.util.List;

@Controller("/users")
public class UserController {

    @Inject
    private UserService userService;

    @Get
    public List<String> list() {
        return userService.list();
    }

    @Post
    public String add(@Body String name) {
        return userService.add(name);
    }
}

Injection via @Inject—resolved at runtime or AOT by Micronaut. Slimmer controller delegates to the service. Gotcha: import jakarta.inject.Inject (not javax in 2026). Hot-reload works automatically in dev.

Run and Test the API

Build, run in dev mode, and test with curl. The app listens on port 8080 by default.

Run and Test

terminal-run-test.sh

gradle run --continuous

# Dans un autre terminal :
curl http://localhost:8080/users
curl -X POST -H "Content-Type: text/plain" -d "Alice" http://localhost:8080/users
curl http://localhost:8080/users

--continuous enables hot-reload. First curl: []. POST adds Alice, second: [Alice]. Stop with Ctrl+C. Gotcha: ensure port is free; use gradle micronautFeatureAot:compile for AOT.

Compile to Native (Optional)

terminal-native.sh

gradle nativeCompile
./build/native/nativeCompile/ma_premiere_api

Compiles to a GraalVM native executable (<50MB, 10ms startup). Requires GraalVM via SDKMAN. Endpoints work the same. Great for Docker/K8s in 2026.

Best Practices

Always use singletons for services: Micronaut optimizes scopes by default.
Enable validation: Add @Valid on @Body with Bean Validation 3.0.
Secure early: Add Micronaut Security with --features jwt on create-app.
Unit tests: Write with @MicronautTest for auto-mocking.
Structured logs: Configure SLF4J + JSON in application.yml.

Common Errors to Avoid

Forgetting @Inject: Triggers NoSuchBeanException at runtime—always inject explicitly.
Java <17: Compatibility issues; check sdk current java.
No hot-reload: Use gradle run --continuous, not java -jar.
CORS issues: Add @CrossOrigin on controllers for frontend apps.

Next Steps

Master Micronaut with our Advanced Java Training. Check the official docs and explore Data, Security, Kubernetes. Try Micronaut Launch online for quick prototypes.