Consuming External APIs in Micronaut

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:


GET https://jsonplaceholder.typicode.com/users/1

Sample response:


{
  "id": 1,
  "name": "Leanne Graham",
  "username": "Bret",
  "email": "Sincere@april.biz"
}

Step 1: Create a New Micronaut Project

Use Micronaut CLI or Micronaut Launch.


mn create-app com.kscodes.micronaut.apiclient --build=maven --lang=java

Step 2: Add HTTP Client Dependency

In your pom.xml, verify you have:



    io.micronaut
    micronaut-http-client

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.


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.


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.


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 User Java 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:


{
  "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


user-client:
  url: https://jsonplaceholder.typicode.com

Client Interface


@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.