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.0.0</version>
</dependency>

Install the SDK locally from source first:

cd sdk/java && mvn install -DskipTests

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 (01-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 (02-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.0.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.