Java SDK

Purpose

The Java SDK provides an ApiMapperClient using virtual threads and a Spring AI auto-configuration adapter.

Main Capabilities

• Java 21 virtual threads — non-blocking without reactive programming
• CompletableFuture-based public API
• Three authentication modes: API key, OAuth2 client credentials, delegated bearer
• SLF4J logging — callers supply the backend (Logback, Log4j2, etc.)
• Spring AI FunctionCallback adapter with @EnableApiMapper-style auto-configuration

Artifacts

Installation

<dependency>
  <groupId>com.codedprojects</groupId>
  <artifactId>api-mapper-client</artifactId>
  <version>1.1.0</version>
</dependency>

Construction

var opts = ApiMapperClientOptions.builder()
    .baseUrl(System.getenv("APIMAPPER_BASE_URL"))
    .tenantId(UUID.fromString(System.getenv("APIMAPPER_TENANT_ID")))
    .clientId("my-app")
    .systemPromptResourceUri("apimapper://toolsets/system-prompt")
    .credentials(new ApiKeyCredentialProvider(System.getenv("APIMAPPER_API_KEY")))
    .build();

try (var client = new ApiMapperClient(opts)) {
    // use client
}

See SDK Authentication for OAuth2 and delegated bearer options.

Raw Client

try (var client = new ApiMapperClient(opts)) {
    var systemPrompt = client.getSystemPrompt().get();
    var tools        = client.getTools().get();

    System.out.printf("System prompt: %d chars%n",
        systemPrompt != null ? systemPrompt.length() : 0);

    System.out.printf("Tools: %s%n",
        tools.stream().map(McpTool::name).collect(Collectors.joining(", ")));

    var result = client.invokeTool(tools.get(0).name(), Map.of()).get();
    System.out.println(result != null ? result.toText() : "(null)");
}

Spring AI Agent

Add the Spring AI adapter and configure via application.yml.

<dependency>
  <groupId>com.codedprojects</groupId>
  <artifactId>api-mapper-spring-ai</artifactId>
  <version>1.1.0</version>
</dependency>

api-mapper:
  base-url:    https://gateway.example.com
  tenant-id:   ${API_MAPPER_TENANT_ID}
  client-id:   my-app
  system-prompt-resource-uri: apimapper://toolsets/system-prompt
  api-key:     ${API_MAPPER_API_KEY}

spring:
  ai:
    openai:
      api-key: ${SPRING_AI_OPENAI_API_KEY}
      chat:
        options:
          model: gpt-4o

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

    @Bean
    ApplicationRunner runner(ChatClient.Builder builder, ApiMapperClient mapper) {
        return _ -> {
            var systemPrompt = mapper.getSystemPrompt().get();

            var answer = builder
                .defaultSystem(systemPrompt != null ? systemPrompt : "You are a helpful assistant.")
                .build()
                .prompt()
                .user("What tools are available?")
                .call()
                .content();

            System.out.println(answer);
        };
    }
}

The auto-configuration registers one FunctionCallback bean per Runtime tool. Spring AI discovers them automatically and makes them available to any ChatClient.

Logging

The SDK uses SLF4J. Add Logback or Log4j2 to your runtime classpath, then configure the com.codedprojects.apimapper.client logger.

<!-- logback.xml -->
<logger name="com.codedprojects.apimapper.client" level="INFO"/>

Set to DEBUG to see MCP handshakes, per-tool invocation events, and cache hits (when caching is explicitly enabled). Auth header values and secrets are never logged.

Correlation IDs

Set correlationIdProvider to send the calling application's own identifier to the Runtime on every request, or pass one as the third argument to invokeTool for a single call. The per-call value wins.

var options = ApiMapperClientOptions.builder()
        // Invoked once per request, so the MDC value resolves per request.
        .correlationIdProvider(() -> MDC.get("traceId"))
        .build();

var result = client.invokeTool("crm-lookup", args, "order-4711").join();

The existing invokeTool(String, Map) overload is unchanged, so no existing call site needs to move.

A provider that throws is logged and ignored rather than failing the tool call. When the Runtime does not echo the value back on X-External-Correlation-Id, the client logs a warning — see SDK → Correlation IDs for the accepted format.