Building a REST API with Solon 4.0: A Step-by-Step Guide

Why Solon for REST APIs?

What drew me to Solon in the first place was how little code it takes to get something running. There's no heavy annotation processing, no XML configuration files to maintain, and the startup time is genuinely fast — we're talking sub-second for most small to mid-sized applications.

But more importantly, the API design feels intuitive if you've worked with modern Java frameworks. @Controller, @Mapping, @Inject — nothing exotic. You'll feel at home within minutes.

Prerequisites

• Java 17+ installed on your machine
• Maven 3.6+ (or use the Maven wrapper)
• Your favorite IDE (I use IntelliJ, but VS Code works fine too)

Project Setup

Let's start by creating a Maven project. I prefer doing this manually so I understand every piece that goes in.

Create the following directory structure:

user-api/
├── pom.xml
└── src/
    └── main/
        ├── java/
        │   └── com/
        │       └── demo/
        │           ├── App.java
        │           ├── controller/
        │           │   └── UserController.java
        │           ├── model/
        │           │   └── User.java
        │           └── mapper/
        │               └── UserMapper.java
        └── resources/
            ├── app.yml
            └── mybatis/
                └── UserMapper.xml

pom.xml

Here's the Maven setup. I'm using solon-web as the core dependency — it bundles everything you need for REST API development:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.demo</groupId>
    <artifactId>user-api</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <java.version>17</java.version>
        <solon.version>4.0.2</solon.version>
    </properties>

    <dependencies>
        <!-- Solon Web (MVC + HTTP server) -->
        <dependency>
            <groupId>org.noear</groupId>
            <artifactId>solon-web</artifactId>
            <version>${solon.version}</version>
        </dependency>

        <!-- MyBatis-Solon integration -->
        <dependency>
            <groupId>org.noear</groupId>
            <artifactId>solon-data-mybatis-plus-extension-solon-plugin</artifactId>
            <version>${solon.version}</version>
        </dependency>

        <!-- H2 database (for development) -->
        <dependency>
            <groupId>com.h2database</groupId>
            <artifactId>h2</artifactId>
            <version>2.2.224</version>
            <scope>runtime</scope>
        </dependency>

        <!-- Lombok (optional, but saves boilerplate) -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.30</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.11.0</version>
                <configuration>
                    <source>17</source>
                    <target>17</target>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

Note: I'm using solon-data-mybatis-plus-extension-solon-plugin here because it bundles MyBatis with useful extensions. If you prefer plain MyBatis, solon-data-mybatis-solon-plugin works too.

The Main Class

Every Solon application needs an entry point. It's refreshingly minimal:

package com.demo;

import org.noear.solon.Solon;

public class App {
    public static void main(String[] args) {
        Solon.start(App.class, args);
    }
}

That's it. Solon.start() scans the package, picks up your controllers and configurations, and starts the embedded server (default port is 8080). No @SpringBootApplication, no @EnableAutoConfiguration.

Configuration File

Solon uses app.yml by default (YAML is my preference, but it supports .properties too):

server:
  port: 8080

solon.data:
  schema: classpath:db/schema.sql  # Auto-run on startup

datasource:
  user:
    class: org.h2.Driver
    url: jdbc:h2:mem:userdb
    username: sa
    password:

mybatis:
  user:
    mapperPackage: com.demo.mapper

Let me explain this quickly:

• solon.data.schema points to a SQL file that creates our tables on startup
• datasource.user defines an H2 in-memory database named userdb
• mybatis.user.mapperPackage tells MyBatis where to find mapper interfaces

Create a SQL file at src/main/resources/db/schema.sql:

CREATE TABLE IF NOT EXISTS users (
    id      BIGINT AUTO_INCREMENT PRIMARY KEY,
    name    VARCHAR(50) NOT NULL,
    email   VARCHAR(100) NOT NULL,
    age     INT DEFAULT 0,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Creating the Domain Model

I like keeping things simple. A User model with a few fields:

package com.demo.model;

import lombok.Data;

@Data
public class User {
    private Long id;
    private String name;
    private String email;
    private Integer age;
}

Data Access Layer with MyBatis

The Mapper Interface

package com.demo.mapper;

import com.demo.model.User;
import org.apache.ibatis.annotations.Mapper;

import java.util.List;

@Mapper
public interface UserMapper {
    List<User> findAll();
    User findById(long id);
    void insert(User user);
    int update(User user);
    int deleteById(long id);
}

The XML Mapper

Place this at src/main/resources/mybatis/UserMapper.xml:

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
        "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.demo.mapper.UserMapper">

    <resultMap id="userMap" type="com.demo.model.User">
        <id column="id" property="id"/>
        <result column="name" property="name"/>
        <result column="email" property="email"/>
        <result column="age" property="age"/>
    </resultMap>

    <select id="findAll" resultMap="userMap">
        SELECT * FROM users ORDER BY id
    </select>

    <select id="findById" resultMap="userMap">
        SELECT * FROM users WHERE id = #{id}
    </select>

    <insert id="insert" useGeneratedKeys="true" keyProperty="id">
        INSERT INTO users (name, email, age)
        VALUES (#{name}, #{email}, #{age})
    </insert>

    <update id="update">
        UPDATE users
        SET name = #{name},
            email = #{email},
            age = #{age}
        WHERE id = #{id}
    </update>

    <delete id="deleteById">
        DELETE FROM users WHERE id = #{id}
    </delete>

</mapper>

Building the REST Controller

Now for the main event — the controller. This is where Solon's simplicity really shines:

package com.demo.controller;

import com.demo.mapper.UserMapper;
import com.demo.model.User;
import org.noear.solon.annotation.*;

import java.util.HashMap;
import java.util.List;
import java.util.Map;

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

    @Inject
    private UserMapper userMapper;

    @Get
    public List<User> getAll() {
        return userMapper.findAll();
    }

    @Get
    @Mapping("/{id}")
    public User getById(@Path long id) {
        return userMapper.findById(id);
    }

    @Post
    public Map<String, Object> create(@Body User user) {
        userMapper.insert(user);
        Map<String, Object> result = new HashMap<>();
        result.put("id", user.getId());
        result.put("message", "User created successfully");
        return result;
    }

    @Put
    @Mapping("/{id}")
    public Map<String, String> update(@Path long id, @Body User user) {
        user.setId(id);
        int rows = userMapper.update(user);
        Map<String, String> result = new HashMap<>();
        if (rows > 0) {
            result.put("message", "User updated successfully");
        } else {
            result.put("message", "User not found");
        }
        return result;
    }

    @Delete
    @Mapping("/{id}")
    public Map<String, String> delete(@Path long id) {
        int rows = userMapper.deleteById(id);
        Map<String, String> result = new HashMap<>();
        if (rows > 0) {
            result.put("message", "User deleted successfully");
        } else {
            result.put("message", "User not found");
        }
        return result;
    }
}

A few things I really like here:

• @Inject instead of @Autowired — less magic, more explicit
• @Get, @Post, @Put, @Delete — HTTP-method-specific annotations that keep things readable
• @Body for automatic request body deserialization (works with JSON by default)
• @Path for path variables — no @PathVariable("id") ceremony needed

Solon uses solon.serialization.json under the hood, which auto-detects Jackson if it's on the classpath. Since solon-web brings Jackson in transitively, JSON works out of the box.

Running and Testing

Start the Application

mvn clean compile exec:java -Dexec.mainClass="com.demo.App"

Or simply run App.main() from your IDE. You should see something like:

2026-06-27 00:15:32.145 INFO  [main] - Solon v4.0.2 started in 0.86s
2026-06-27 00:15:32.150 INFO  [main] - HttpServer on port 8080

0.86 seconds. That's what surprised me the most the first time I ran it — the framework starts in under a second even with MyBatis and H2 wired up.

Test the API

Let's exercise the endpoints:

# Create a user
curl -X POST http://localhost:8080/api/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice","email":"[e-mail]","age":28}'

# Response: {"id":1,"message":"User created successfully"}

# Create another user
curl -X POST http://localhost:8080/api/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Bob","email":"[e-mail]","age":35}'

# Get all users
curl http://localhost:8080/api/users

# Response:
# [{"id":1,"name":"Alice","email":"[e-mail]","age":28,"createdAt":...},
#  {"id":2,"name":"Bob","email":"[e-mail]","age":35,"createdAt":...}]

# Get a single user
curl http://localhost:8080/api/users/1

# Update a user
curl -X PUT http://localhost:8080/api/users/1 \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice Johnson","email":"[e-mail]","age":29}'

# Delete a user
curl -X DELETE http://localhost:8080/api/users/2

Everything works as expected. JSON serialization is clean — camelCase Java fields map to camelCase JSON keys by default, and the created_at column is automatically handled.

What I Found Interesting

A few takeaways from building this:

1. Startup time is addictive. Once you experience sub-second startup, waiting 5–10 seconds for other frameworks to boot starts to feel painful.

2. The API surface is small but sufficient. Solon doesn't try to do everything — it does the core things well and gets out of your way. The entire controller above uses only 6 annotations.

3. Minimal surprises. Everything worked on the first run (once I got the config right). No mysterious auto-configuration failures, no circular dependency issues.

Summary

We built a complete REST API with Solon 4.0 in under 100 lines of Java code (excluding config and XML). The framework's philosophy is clear: be fast, stay simple, and trust the developer.

I've put the full project on GitHub if you want to clone it and play around. In my next post, I'll explore adding validation, exception handling, and maybe a dash of AOP.

---

Have you tried Solon for building APIs? I'd love to hear about your experience. Drop a comment or reach out — I'm still learning the framework myself, and there's always something new to discover.