Javalin Tutorial: Build a Java REST API

Javalin is a lightweight web framework for building REST APIs and web applications in Java or Kotlin. This Javalin tutorial starts with a working server and adds routing, JSON responses, validation, errors, WebSockets, and asynchronous work.

Javalin quick start

Javalin 7 requires Java 17 or newer. Add the current Javalin dependency to Maven:

<dependency>
    <groupId>io.javalin</groupId>
    <artifactId>javalin</artifactId>
    <version>7.2.2</version>
</dependency>

Then create and start the application:

import io.javalin.Javalin;

public class Application {
    public static void main(String[] args) {
        Javalin.create(config -> {
            config.routes.get("/", ctx -> ctx.result("Hello, Javalin!"));
        }).start(7070);
    }
}

Open http://localhost:7070. The response is Hello, Javalin!.

Why Javalin?

• No boilerplate: Start a server in 3 lines of code.
• Flexible routing: Define HTTP endpoints with lambda expressions.
• WebSocket support: Build real-time features effortlessly.
• Async-ready: Handle long-running tasks without blocking threads.
• Kotlin-friendly: Leverage Kotlin’s concise syntax for even cleaner code.

Getting Started: Hello World in Java & Kotlin

1. Java Example

Add Maven dependency:

<dependency>
    <groupId>io.javalin</groupId>
    <artifactId>javalin</artifactId>
    <version>7.2.2</version>
</dependency>

Start the server:

import io.javalin.Javalin;

public class HelloWorld {
    public static void main(String[] args) {
        Javalin.create(config ->
            config.routes.get("/", ctx -> ctx.result("Hello from Java!"))
        ).start(7070);
    }
}

Output:
Visit http://localhost:7070 in your browser. You’ll see:

Hello from Java!

2. Kotlin Example

Add Gradle dependency:

implementation("io.javalin:javalin:7.2.2")

Start the server:

import io.javalin.Javalin

fun main() {
    Javalin.create { config ->
        config.routes.get("/") { ctx -> ctx.result("Hello from Kotlin!") }
    }.start(7070)
}

Output:
Visit http://localhost:7070:

Hello from Kotlin!

Key Features with Code Examples

1. Routing & Path Parameters

config.routes.get("/greet/{name}", ctx -> {
    String name = ctx.pathParam("name");
    ctx.result("Hello, " + name + "!");
});

Test:
http://localhost:7070/greet/Alice →

Hello, Alice!

2. JSON Responses

config.routes.get("/api/users", ctx -> {
    Map<String, Object> user = Map.of("id", 1, "name", "Bob");
    ctx.json(user); // Auto-converts to JSON
});

Output:

{"id":1,"name":"Bob"}

3. WebSocket (Real-Time Updates)

config.routes.ws("/chat", ws -> {
    ws.onConnect(ctx -> System.out.println("Client connected!"));
    ws.onMessage(ctx -> {
        String message = ctx.message();
        ctx.send("Echo: " + message);
    });
});

Test:
Use a WebSocket client (e.g., browser dev tools) to connect to ws://localhost:7070/chat and send a message.

4. Async Handling

config.routes.get("/async", ctx -> {
    ctx.async(() -> {
        Thread.sleep(1000); // Simulate blocking work
        ctx.result("Async response!");
    });
});

Output (after 1 second):

Async response!

Javalin FAQ

What is Javalin used for?

Javalin is used to build Java and Kotlin REST APIs, traditional web applications, WebSocket services, and lightweight microservices.

Is Javalin a web server?

Javalin is a web framework that runs on an embedded Jetty server, so an application can be packaged and started without deploying a WAR file to a separate server.

Is Javalin similar to Spring Boot?

Both can create Java web applications, but Javalin exposes a smaller, less opinionated API. Spring Boot provides a much larger ecosystem and more built-in conventions.

Conclusion

Javalin is a practical choice when you want a small, unopinionated Java or Kotlin web framework. Start with a few routes, then add validation, authentication, persistence, OpenAPI, and deployment configuration as the application grows.

Next Steps:

• Explore Javalin’s official docs.
• Join the Discord community for help.

Happy coding! 🚀