GuicedEE REST Client

Annotation-driven REST client for GuicedEE applications using the Vert.x 5 WebClient. Declare an @Endpoint on any RestClient<Send, Receive> field, add @Named, and inject — URL, HTTP method, authentication, timeouts, and connection options are all driven from the annotation. Every call returns a Uni<Receive> for fully reactive composition.

Built on Vert.x Web Client · Google Guice · Mutiny · Jackson · JPMS module com.guicedee.rest.client · Java 25+

📦 Installation

<dependency>
  <groupId>com.guicedee</groupId>
  <artifactId>rest-client</artifactId>
</dependency>

Gradle (Kotlin DSL)

implementation("com.guicedee:rest-client:2.0.0-SNAPSHOT")

✨ Features

Zero-boilerplate REST calls — annotate a field with @Endpoint and @Named, inject, call send() or publish()
Fully typed — RestClient<Send, Receive> preserves generic types for Jackson (de)serialization, including collections and nested generics
Reactive — every call returns Uni<Receive> for non-blocking composition; fire-and-forget via publish()
Annotation-driven configuration — URL, HTTP method, protocol version, authentication, timeouts, and connection tuning all declared on the field
Multiple authentication strategies — Bearer/JWT, Basic, and API Key with environment variable placeholders for secrets
Path parameters — {paramName} placeholders in URLs with a fluent pathParam() builder, URL-encoded per RFC 3986
Environment variable overrides — every annotation attribute can be overridden via REST_CLIENT_* environment variables without code changes
Package-level @Endpoint — declare shared base URL and options on package-info.java for all clients in a package
RestClientConfigurator SPI — hook into WebClient construction for custom SSL, proxy, or other Vert.x options
Rich error model — RestClientException carries HTTP status, status message, response body, and cause with isClientError() / isServerError() / isTransportError() helpers
Cached WebClients — one WebClient per endpoint name, reused across injections

🚀 Quick Start

Step 1 — Declare a REST client field:

public class UserService {

    @Endpoint(url = "https://api.example.com/users", method = "POST",
              security = @EndpointSecurity(value = SecurityType.Bearer,
                                           token = "${API_TOKEN}"))
    @Named("create-user")
    private RestClient<CreateUserRequest, UserResponse> createUserClient;

    public Uni<UserResponse> createUser(CreateUserRequest request) {
        return createUserClient.send(request);
    }
}

Step 2 — Bootstrap GuicedEE (endpoints are discovered and bound automatically):

IGuiceContext.registerModuleForScanning.add("my.app");
IGuiceContext.instance();

That's it. RestClientRegistry discovers the @Endpoint field, RestClientBinder creates the Guice binding, and the RestClient is ready for injection.

Note: Only one field needs the @Endpoint annotation to define the endpoint. After that, any other class can inject the same client using just @Inject and @Named — no @Endpoint required:
public class OrderService {

    @Inject
    @Named("create-user")
    private RestClient<CreateUserRequest, UserResponse> createUserClient;
}

📐 Architecture

Startup
  IGuiceContext.instance()
   └─ IGuicePreStartup hooks
       └─ RestClientPreStartup         (scans for @Endpoint-annotated fields)
   └─ IGuiceModule hooks
       └─ RestClientBinder             (binds RestClient instances per @Named endpoint)
           ├─ RestClientRegistry       (metadata: URL, types, security, options)
           ├─ WebClient cache          (one Vert.x WebClient per endpoint)
           └─ RestClientConfigurator   (SPI for custom WebClientOptions)

Request lifecycle

restClient.send(body)
 → Uni.createFrom().deferred()
   → Resolve path parameters ({param} → value)
   → Parse URI (host, port, path, scheme)
   → Create HttpRequest via WebClient
   → Apply timeouts (connect, idle, read)
   → Apply default headers (Accept, Content-Type)
   → Apply authentication (Bearer / Basic / ApiKey)
   → Apply query params from URI + additional params
   → Serialize body via DefaultObjectMapper → Buffer
   → Send request (sendBuffer / send)
   → Map response:
       2xx → Deserialize body via DefaultObjectMapper → Receive
       non-2xx → RestClientException (status, message, body)
       transport error → RestClientException (cause)

🛣️ Endpoint Declaration

Field-level `@Endpoint`

The primary way to declare a REST client — annotate a RestClient<Send, Receive> field:

@Endpoint(url = "https://api.example.com/users/{userId}",
          method = "GET",
          options = @EndpointOptions(connectTimeout = 5000, readTimeout = 10000))
@Named("get-user")
private RestClient<Void, UserResponse> getUserClient;

Package-level `@Endpoint`

Declare a shared base URL and default options for all clients in a package via package-info.java:

@Endpoint(url = "http://localhost:8080/api",
          options = @EndpointOptions(readTimeout = 1000))
package com.example.api;

import com.guicedee.rest.client.annotations.Endpoint;
import com.guicedee.rest.client.annotations.EndpointOptions;

Field-level URLs that start with / are appended to the package-level base URL.

Binding names

The @Named annotation determines the Guice binding key. Once an @Endpoint is registered, the client can then be injected by name.

// Inject by name
@Named("create-user")
@Inject
private RestClient<CreateUserRequest, UserResponse> client;

// Or retrieve programmatically
RestClient<?, ?> client = IGuiceContext.get(
    Key.get(RestClient.class, Names.named("create-user")));

📡 Sending Requests

Simple send (no body)

Uni<UserResponse> response = client.send();

Send with body

Uni<UserResponse> response = client.send(new CreateUserRequest("Alice"));

Send with headers and query parameters

Uni<UserResponse> response = client.send(
    body,
    Map.of("X-Request-Id", "abc123"),      // headers
    Map.of("page", "1", "limit", "10")     // query params
);

Path parameters

Use {paramName} placeholders in the endpoint URL:

@Endpoint(url = "https://api.example.com/users/{userId}/orders/{orderId}",
          method = "GET")
@Named("get-order")
private RestClient<Void, OrderResponse> orderClient;

// Fluent builder
Uni<OrderResponse> response = orderClient
    .pathParam("userId", "123")
    .pathParam("orderId", "456")
    .send();

Path parameter values are URL-encoded automatically (RFC 3986). Unresolved placeholders throw IllegalArgumentException.

Fire-and-forget

Uni<Void> done = client.publish(body);

Fluent request builder

Chain path parameters, headers, and query parameters:

Uni<OrderResponse> response = orderClient
    .pathParam("userId", "123")
    .pathParam("orderId", "456")
    .headers(Map.of("X-Correlation-Id", correlationId))
    .queryParams(Map.of("expand", "items"))
    .send();

📤 Response Handling

Typed deserialization

Response bodies are deserialized using the DefaultObjectMapper (Jackson) based on the Receive type parameter:

Receive type	Behavior
`String`	Response body as UTF-8 string
`byte[]`	Raw response bytes
Any class	Jackson deserialization via full generic type
`Void` / `Object`	Raw `Buffer` returned

Status code handling

Status	Behavior
2xx	Deserialized body returned in `Uni`
Non-2xx	`Uni.failure(RestClientException)` with status, message, and body
Transport error	`Uni.failure(RestClientException)` with cause

Error handling

client.send(request)
    .subscribe().with(
        response -> log.info("Success: {}", response),
        err -> {
            if (err instanceof RestClientException rce) {
                if (rce.isClientError()) {
                    log.warn("Client error {}: {}", rce.getStatusCode(), rce.getResponseBody());
                } else if (rce.isServerError()) {
                    log.error("Server error {}: {}", rce.getStatusCode(), rce.getStatusMessage());
                } else if (rce.isTransportError()) {
                    log.error("Connection failed: {}", rce.getMessage());
                }
            }
        }
    );

🔒 Security

`@EndpointSecurity`

Authentication is configured via the security attribute of @Endpoint:

@Endpoint(url = "https://api.example.com/data",
          security = @EndpointSecurity(value = SecurityType.Bearer,
                                       token = "${API_TOKEN}"))

Authentication strategies

`SecurityType`	Header	Source attributes
`Bearer`	`Authorization: Bearer <token>`	`token`
`JWT`	`Authorization: Bearer <token>`	`token`
`Basic`	`Authorization: Basic <base64>`	`username`, `password`
`ApiKey`	`<apiKeyHeader>: <apiKey>`	`apiKey`, `apiKeyHeader` (default `X-API-Key`)
`None`	(no authentication)	—

Environment variable placeholders

All credential values support ${VAR_NAME} syntax, resolved via system properties or environment variables:

@EndpointSecurity(value = SecurityType.Bearer, token = "${API_TOKEN}")

export API_TOKEN=eyJhbGciOiJIUzI1NiIs...

Per-endpoint environment overrides

Security values can also be overridden via naming convention:

Variable	Purpose
`REST_CLIENT_TOKEN_<endpointName>`	Override Bearer/JWT token
`REST_CLIENT_USERNAME_<endpointName>`	Override Basic username
`REST_CLIENT_PASSWORD_<endpointName>`	Override Basic password
`REST_CLIENT_API_KEY_<endpointName>`	Override API key
`REST_CLIENT_API_KEY_HEADER_<endpointName>`	Override API key header name

⚙️ Configuration

`@EndpointOptions`

Connection tuning and behavior options. All timing values are in milliseconds; 0 means "use Vert.x default":

Attribute	Default	Purpose
`connectTimeout`	`0`	TCP connect timeout (ms)
`idleTimeout`	`0`	Idle connection timeout (ms)
`readTimeout`	`0`	Response timeout per request (ms)
`trustAll`	`false`	Trust all server certificates (dev only)
`verifyHost`	`true`	Verify server hostname against certificate
`ssl`	`false`	Force SSL/TLS (auto-detected from `https` URLs)
`maxPoolSize`	`0`	Max connection pool size
`keepAlive`	`true`	TCP keep-alive between requests
`decompression`	`true`	Auto-decompress gzip/deflate responses
`followRedirects`	`true`	Follow HTTP redirects automatically
`maxRedirects`	`0`	Max redirect hops
`defaultContentType`	`application/json`	Default `Content-Type` header
`defaultAccept`	`application/json`	Default `Accept` header
`retryAttempts`	`0`	Retry count on connection failure
`retryDelay`	`1000`	Delay between retries (ms)

@Endpoint(url = "https://slow-api.example.com/data",
          method = "GET",
          options = @EndpointOptions(
              connectTimeout = 5000,
              readTimeout = 30000,
              maxPoolSize = 10,
              retryAttempts = 3,
              retryDelay = 2000
          ))
@Named("slow-api")
private RestClient<Void, DataResponse> slowApiClient;

Environment variable overrides

Every @EndpointOptions attribute can be overridden per endpoint via environment variables:

Variable	Purpose
`REST_CLIENT_URL_<name>`	Override endpoint URL
`REST_CLIENT_METHOD_<name>`	Override HTTP method
`REST_CLIENT_PROTOCOL_<name>`	Override protocol (`HTTP` / `HTTP2`)
`REST_CLIENT_CONNECT_TIMEOUT_<name>`	Override connect timeout
`REST_CLIENT_IDLE_TIMEOUT_<name>`	Override idle timeout
`REST_CLIENT_READ_TIMEOUT_<name>`	Override read timeout
`REST_CLIENT_TRUST_ALL_<name>`	Override trust-all flag
`REST_CLIENT_VERIFY_HOST_<name>`	Override hostname verification
`REST_CLIENT_SSL_<name>`	Override SSL flag
`REST_CLIENT_MAX_POOL_SIZE_<name>`	Override connection pool size
`REST_CLIENT_KEEP_ALIVE_<name>`	Override keep-alive flag
`REST_CLIENT_DECOMPRESSION_<name>`	Override decompression flag
`REST_CLIENT_FOLLOW_REDIRECTS_<name>`	Override follow-redirects flag
`REST_CLIENT_MAX_REDIRECTS_<name>`	Override max redirect hops
`REST_CLIENT_CONTENT_TYPE_<name>`	Override default Content-Type
`REST_CLIENT_ACCEPT_<name>`	Override default Accept
`REST_CLIENT_RETRY_ATTEMPTS_<name>`	Override retry count
`REST_CLIENT_RETRY_DELAY_<name>`	Override retry delay

Where <name> is the @Named value of the endpoint.

HTTP/2

@Endpoint(url = "https://http2-api.example.com/stream",
          method = "GET",
          protocol = Protocol.HTTP2)
@Named("http2-api")
private RestClient<Void, StreamResponse> http2Client;

🔌 SPI Extension Points

`RestClientConfigurator`

Hook into WebClientOptions construction for custom SSL keystores, proxy settings, or other Vert.x options not covered by the annotation model:

public class MyRestClientConfigurator implements RestClientConfigurator {

    @Override
    public WebClientOptions configure(String endpointName, Endpoint endpoint,
                                      WebClientOptions options) {
        if ("secure-api".equals(endpointName)) {
            options.setKeyCertOptions(myKeyCert);
            options.setProxyOptions(new ProxyOptions()
                .setHost("proxy.internal").setPort(3128));
        }
        return options;
    }
}

Register via JPMS:

module my.app {
    requires com.guicedee.rest.client;

    provides com.guicedee.rest.client.RestClientConfigurator
        with my.app.MyRestClientConfigurator;
}

💉 Dependency Injection

RestClient instances are bound by RestClientBinder using the full parameterized type and @Named qualifier:

public class OrderService {

    @Inject
    @Endpoint(url = "https://api.example.com/orders", method = "POST")
    @Named("create-order")
    private RestClient<OrderRequest, OrderResponse> orderClient;

    @Inject
    @Endpoint(url = "https://api.example.com/orders/{id}", method = "GET")
    @Named("get-order")
    private RestClient<Void, OrderResponse> getOrderClient;

    public Uni<OrderResponse> createOrder(OrderRequest request) {
        return orderClient.send(request);
    }

    public Uni<OrderResponse> getOrder(String id) {
        return getOrderClient.pathParam("id", id).send();
    }
}

Injection point detection

RestClientInjectionPointProvision implements InjectionPointProvider to detect @Endpoint-annotated fields, ensuring Guice creates bindings for all discovered endpoints at startup.

❌ Error Handling

`RestClientException`

All failures — HTTP errors, deserialization errors, and transport errors — are surfaced as RestClientException:

Method	Returns `true` when
`isClientError()`	Status 400–499
`isServerError()`	Status 500–599
`isTransportError()`	No HTTP status (connection failure)

Getter	Purpose
`getStatusCode()`	HTTP status code (0 if transport error)
`getStatusMessage()`	HTTP status message or error description
`getResponseBody()`	Raw response body (if available)

🔄 Startup Flow

IGuiceContext.instance()
 └─ IGuicePreStartup hooks
     └─ RestClientPreStartup (sortOrder = MIN_VALUE + 100)
         └─ RestClientRegistry.scanAndRegisterEndpoints()
             ├─ ClassGraph scan for @Endpoint-annotated fields
             ├─ Extract @Named binding name, URL, Send/Receive types
             ├─ Wrap annotations with environment variable resolution
             └─ Populate metadata maps (definitions, URLs, types)
 └─ IGuiceModule hooks
     └─ RestClientBinder
         ├─ scanAndRegisterEndpoints() (idempotent guard)
         ├─ For each endpoint:
         │   ├─ Build Key<RestClient<Send,Receive>> + @Named
         │   ├─ Build WebClientOptions from @EndpointOptions
         │   ├─ Apply RestClientConfigurator SPIs
         │   ├─ Cache WebClient per endpoint name
         │   └─ bind(key).toProvider(RestClient::new)
         └─ InjectionPointProvider detects @Endpoint fields

🗺️ Module Graph

com.guicedee.rest.client
 ├── com.guicedee.client              (GuicedEE SPI contracts, Environment)
 ├── com.guicedee.vertx               (Vert.x lifecycle, VertXPreStartup)
 ├── com.guicedee.jsonrepresentation   (DefaultObjectMapper binding)
 ├── io.vertx.web.client              (Vert.x WebClient)
 ├── io.vertx.core                    (Vert.x core, Future)
 ├── com.fasterxml.jackson.databind   (Jackson ObjectMapper)
 ├── io.smallrye.mutiny               (Uni reactive type)
 └── com.google.guice                 (Guice injection)

🧩 JPMS

Module name: com.guicedee.rest.client

The module:

exports com.guicedee.rest.client, com.guicedee.rest.client.annotations, com.guicedee.rest.client.implementations
provides IGuiceModule with RestClientBinder
provides IGuicePreStartup with RestClientPreStartup
provides InjectionPointProvider with RestClientInjectionPointProvision
uses RestClientConfigurator

In non-JPMS environments, META-INF/services discovery still works.

🏗️ Key Classes

Class	Package	Role
`RestClient`	`client`	Injectable REST client — `send()`, `publish()`, `pathParam()`, response deserialization
`RestClient.RequestBuilder`	`client`	Fluent builder for path params, headers, and query params
`RestClientException`	`client`	Unchecked exception with status code, message, body, and error category helpers
`RestClientConfigurator`	`client`	SPI for customizing `WebClientOptions` per endpoint
`Endpoint`	`annotations`	Annotation declaring URL, method, protocol, security, and options
`EndpointSecurity`	`annotations`	Nested annotation for authentication (Bearer, Basic, ApiKey)
`EndpointOptions`	`annotations`	Nested annotation for timeouts, SSL, pooling, retries
`RestClientRegistry`	`implementations`	Static registry — scans `@Endpoint` fields, stores metadata
`RestClientBinder`	`implementations`	Guice module — binds `RestClient` per `@Named` endpoint
`RestClientProvider`	`implementations`	Guice provider — constructs `RestClient` from registry metadata
`RestClientPreStartup`	`implementations`	Pre-startup hook — triggers classpath scanning
`RestClientInjectionPointProvision`	`implementations`	`InjectionPointProvider` — detects `@Endpoint` fields for binding

🤝 Contributing

Issues and pull requests are welcome — please add tests for new authentication strategies, response types, or WebClient options.

📄 License

Apache 2.0

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
.github/workflows		.github/workflows
.sonarlint		.sonarlint
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pom.xml		pom.xml

Folders and files

Latest commit

History

Repository files navigation

GuicedEE REST Client

📦 Installation

✨ Features

🚀 Quick Start

📐 Architecture

Request lifecycle

🛣️ Endpoint Declaration

Field-level @Endpoint

Package-level @Endpoint

Binding names

📡 Sending Requests

Simple send (no body)

Send with body

Send with headers and query parameters

Path parameters

Fire-and-forget

Fluent request builder

📤 Response Handling

Typed deserialization

Status code handling

Error handling

🔒 Security

@EndpointSecurity

Authentication strategies

Environment variable placeholders

Per-endpoint environment overrides

⚙️ Configuration

@EndpointOptions

Environment variable overrides

HTTP/2

🔌 SPI Extension Points

RestClientConfigurator

💉 Dependency Injection

Injection point detection

❌ Error Handling

RestClientException

🔄 Startup Flow

🗺️ Module Graph

🧩 JPMS

🏗️ Key Classes

🤝 Contributing

📄 License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Field-level `@Endpoint`

Package-level `@Endpoint`

`@EndpointSecurity`

`@EndpointOptions`

`RestClientConfigurator`

`RestClientException`

Packages