When you build REST APIs, one of the most common tasks is to send data in JSON format.
JSON (JavaScript Object Notation) is:
- Easy for machines to parse.
- Easy for humans to read.
- The most common format used in web APIs.
It is super easy to return JSON from REST endpoints in Micronaut. In this post, we’ll walk through:
- Why we return JSON.
- How Micronaut handles JSON.
- Complete code examples.
- How Micronaut automatically converts Java objects to JSON.
Why Return JSON?
Let’s say you are building a School Management System.
When a client (browser, mobile app, etc.) requests data, they expect to receive:
|
1 2 3 4 5 6 7 8 |
{ "id": 1, "name": "John Doe", "grade": "5th" } |
You don’t want to manually convert Java objects to JSON strings.
Micronaut does that for you automatically!
Micronaut and JSON — The Magic of Jackson
Micronaut uses Jackson (a popular Java library) to convert Java objects to JSON and back.
- When you return a Java object from a controller, Micronaut automatically converts it into JSON.
- When you receive JSON in a POST request, Micronaut can automatically convert it into a Java object.
This is called Serialization (Java → JSON) and Deserialization (JSON → Java).
Setting Up the Project
We will use Maven for this tutorial.
Generate Project (using Micronaut Launch or CLI)
If you are using CLI:
|
1 2 3 4 |
mn create-app com.kscodes.micronaut.jsonexample --build=maven --lang=java |
Creating a Simple JSON Endpoint
Let’s say we want to return details of a student.
Step 1: Create a Student POJO (Plain Old Java Object)
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 |
package com.kscodes.micronaut.jsonexample; public class Student { private Long id; private String name; private String grade; public Student() { } public Student(Long id, String name, String grade) { this.id = id; this.name = name; this.grade = grade; } public Long getId() { return id; } public String getName() { return name; } public String getGrade() { return grade; } public void setId(Long id) { this.id = id; } public void setName(String name) { this.name = name; } public void setGrade(String grade) { this.grade = grade; } } |
✅ This is a simple POJO that holds student data.
Step 2: Create a REST Controller
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
package com.kscodes.micronaut.jsonexample; import io.micronaut.http.annotation.Controller; import io.micronaut.http.annotation.Get; @Controller("/students") public class StudentController { @Get("/sample") public Student getSampleStudent() { return new Student(1L, "John Doe", "5th"); } } |
✅ Notice:
- We simply return a
Studentobject. - Micronaut will automatically convert it into JSON!
Testing the Endpoint
Run your Micronaut application:
mvn mn:run
Now open your browser or use curl:
http://localhost:8080/students/sample
OR
curl http://localhost:8080/students/sample
You will get:
|
1 2 3 4 5 6 7 8 |
{ "id": 1, "name": "John Doe", "grade": "5th" } |
🎉 Success! — Micronaut automatically converted your Java object into JSON.
Returning Lists of JSON Objects
What if you want to return multiple students?
Simply return a list:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
package com.kscodes.micronaut.jsonexample; import io.micronaut.http.annotation.Controller; import io.micronaut.http.annotation.Get; import java.util.List; @Controller("/students") public class StudentController { @Get("/") public List<Student> getAllStudents() { return List.of( new Student(1L, "John Doe", "5th"), new Student(2L, "Jane Smith", "6th") ); } } |
👉 When you hit:http://localhost:8080/students/
You will get:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
[ { "id": 1, "name": "John Doe", "grade": "5th" }, { "id": 2, "name": "Jane Smith", "grade": "6th" } ] |
Accepting JSON in POST Requests
You can also receive JSON from clients.
Create POST Endpoint
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
package com.kscodes.micronaut.jsonexample; import io.micronaut.http.annotation.Controller; import io.micronaut.http.annotation.Body; import io.micronaut.http.annotation.Post; @Controller("/students") public class StudentController { @Post("/") public Student createStudent(@Body Student student) { // In real app, you would save to DB return student; } } |
✅ The @Body annotation tells Micronaut to map the JSON request body into a Student object.
Test with curl
|
1 2 3 4 5 6 |
curl -X POST http://localhost:8080/students/ \ -H "Content-Type: application/json" \ -d '{"id":3, "name":"Sam Wilson", "grade":"7th"}' |
Response:
|
1 2 3 4 5 6 7 8 |
{ "id": 3, "name": "Sam Wilson", "grade": "7th" } |
Summary Table
| Task | Micronaut Feature |
|---|---|
| Return JSON | Return Java objects |
| Receive JSON | Use @Body |
| Serialization | Automatic with Jackson |
| No extra code | Micronaut does the work |
Conclusion
- ✅ Super easy to return JSON from REST endpoints in Micronaut.
- ✅ You don’t need to manually handle JSON conversion.
- ✅ Micronaut + Jackson handle serialization/deserialization automatically.
You just return Java objects, and Micronaut handles the rest.
Further Reading and References
If you’d like to explore more about returning JSON with Micronaut and related concepts, check out these helpful resources:
- Micronaut Official Documentation — JSON Binding
👉 https://docs.micronaut.io/latest/guide/#jsonBinding
This section explains how Micronaut automatically handles JSON serialization and deserialization using Jackson. - Jackson Project (used by Micronaut for JSON)
👉 https://github.com/FasterXML/jackson
Learn more about the library that powers JSON processing behind the scenes in Micronaut. - REST API Tutorial — What is JSON?
👉 https://restfulapi.net/json-introduction/
For complete beginners who want to better understand JSON format.