So far, we’ve learned how to create REST APIs in Micronaut and return JSON. But in real-world applications, you often need to consume external APIs.
For example:
- Fetching weather information.
- Calling payment gateways.
- Getting stock market data.
- Consuming other microservices inside your company.
✅ The good news:
Micronaut makes this task very simple using @Client and @Get.
In this post, we will learn step-by-step how to call external APIs in Micronaut.
What is @Client?
The @Client annotation allows you to declare an HTTP client interface:
- Micronaut automatically generates the code to make HTTP calls.
- It handles serialization and deserialization.
- You only need to define methods with annotations like
@Get,@Post, etc.
✅ Key takeaway:
You describe what you want to call, Micronaut handles how to call it.
Scenario Example: Fetching a User from an External API
Let’s assume we want to call an external API that returns user details:
|
1 2 3 4 |
GET https://jsonplaceholder.typicode.com/users/1 |
Sample response:
|
1 2 3 4 5 6 7 8 9 |
{ "id": 1, "name": "Leanne Graham", "username": "Bret", "email": "Sincere@april.biz" } |
Step 1: Create a New Micronaut Project
Use Micronaut CLI or Micronaut Launch.
|
1 2 3 4 |
mn create-app com.kscodes.micronaut.apiclient --build=maven --lang=java |
Step 2: Add HTTP Client Dependency
In your pom.xml, verify you have:
|
1 2 3 4 5 6 7 |
<dependency> <groupid>io.micronaut</groupid> <artifactid>micronaut-http-client</artifactid> </dependency> |
Micronaut needs this dependency to enable HTTP Client features.
Step 3: Create a Model Class
This will match the response structure of the external API.
|
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 44 45 46 |
package com.kscodes.micronaut.apiclient; public class User { private Long id; private String name; private String username; private String email; public User() { } public User(Long id, String name, String username, String email) { this.id = id; this.name = name; this.username = username; this.email = email; } public Long getId() { return id; } public String getName() { return name; } public String getUsername() { return username; } public String getEmail() { return email; } public void setId(Long id) { this.id = id; } public void setName(String name) { this.name = name; } public void setUsername(String username) { this.username = username; } public void setEmail(String email) { this.email = email; } } |
✅ Now Micronaut can automatically map the JSON response into this Java object.
Step 4: Create the HTTP Client Interface
Here comes the power of @Client.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
package com.kscodes.micronaut.apiclient; import io.micronaut.http.annotation.Client; import io.micronaut.http.annotation.Get; @Client("https://jsonplaceholder.typicode.com") public interface UserClient { @Get("/users/{id}") User getUserById(Long id); } |
✅ Explanation:
@Client: defines the base URL.@Get: specifies the endpoint and path parameter.- Micronaut auto-generates the implementation at compile time.
Step 5: Create a Controller to Test
Now let’s build a simple controller to test the external API call.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
package com.kscodes.micronaut.apiclient; import io.micronaut.http.annotation.Controller; import io.micronaut.http.annotation.Get; @Controller("/local/users") public class UserController { private final UserClient userClient; public UserController(UserClient userClient) { this.userClient = userClient; } @Get("/{id}") public User fetchUser(Long id) { return userClient.getUserById(id); } } |
✅ When you call http://localhost:8080/local/users/1, Micronaut:
- Invokes your external API client (
UserClient). - Calls
https://jsonplaceholder.typicode.com/users/1. - Converts JSON to
UserJava object. - Returns it as JSON to the caller.
Step 6: Run and Test
Start your application:
mvn mn:run
Test using curl or browser:
http://localhost:8080/local/users/1
Expected result:
|
1 2 3 4 5 6 7 8 9 |
{ "id": 1, "name": "Leanne Graham", "username": "Bret", "email": "Sincere@april.biz" } |
🎉 Success — you just consumed an external API!
Additional Tip: Configurable Base URL
Instead of hardcoding the URL inside @Client, you can also configure it in application.yml.
application.yml
|
1 2 3 4 5 |
user-client: url: https://jsonplaceholder.typicode.com |
Client Interface
|
1 2 3 4 5 6 7 8 |
@Client("${user-client.url}") public interface UserClient { @Get("/users/{id}") User getUserById(Long id); } |
✅ This allows you to easily change the URL for different environments (dev, prod, etc.).
Summary Table
| Micronaut Feature | What it does |
|---|---|
@Client | Declares HTTP Client |
@Get | Specifies GET endpoint |
| Automatic Mapping | Converts JSON to Java |
| Configuration | Allows flexible URLs |
Conclusion
- ✅ Consuming external APIs in Micronaut is super easy.
- ✅ You don’t need to write complex HTTP client code.
- ✅ Micronaut automatically maps JSON to Java.
- ✅ You just define the interface and annotations.
👉 Even complete beginners can build powerful API clients using Micronaut with minimal code.
Further Reading
- Micronaut HTTP Client Documentation
https://docs.micronaut.io/latest/guide/#httpClient - Micronaut @Client Annotation
https://docs.micronaut.io/latest/api/io/micronaut/http/annotation/Client.html - JSONPlaceholder Free API (used in this example)
https://jsonplaceholder.typicode.com/