guicedee-rest-client
Annotation-driven REST client for GuicedEE using Vert.x 5 WebClient: @Endpoint declarations, RestClient<Send, Receive> injection, authentication strategies (Bearer, Basic, API Key, OAuth2, mTLS), path parameters, environment variable overrides, package-level endpoints, service registry integration (bare name or registry: prefix), and RestClientConfigurator SPI. Use when making outbound REST calls, configuring REST client endpoints, or wiring reactive HTTP clients with Guice injection.
Best use case
guicedee-rest-client is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Annotation-driven REST client for GuicedEE using Vert.x 5 WebClient: @Endpoint declarations, RestClient<Send, Receive> injection, authentication strategies (Bearer, Basic, API Key, OAuth2, mTLS), path parameters, environment variable overrides, package-level endpoints, service registry integration (bare name or registry: prefix), and RestClientConfigurator SPI. Use when making outbound REST calls, configuring REST client endpoints, or wiring reactive HTTP clients with Guice injection.
Teams using guicedee-rest-client should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/guicedee-rest-client/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How guicedee-rest-client Compares
| Feature / Agent | guicedee-rest-client | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Annotation-driven REST client for GuicedEE using Vert.x 5 WebClient: @Endpoint declarations, RestClient<Send, Receive> injection, authentication strategies (Bearer, Basic, API Key, OAuth2, mTLS), path parameters, environment variable overrides, package-level endpoints, service registry integration (bare name or registry: prefix), and RestClientConfigurator SPI. Use when making outbound REST calls, configuring REST client endpoints, or wiring reactive HTTP clients with Guice injection.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# GuicedEE REST Client
Annotation-driven REST client using the Vert.x 5 WebClient, fully managed by GuicedEE.
## Core Concept
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.
## Required Flow
1. Add `com.guicedee:rest-client` dependency.
2. Configure `module-info.java`:
```java
module my.app {
requires com.guicedee.rest.client;
opens my.app.clients to com.google.guice, com.guicedee.rest.client;
opens my.app.dto to com.fasterxml.jackson.databind;
}
```
3. Declare a REST client field with `@Endpoint`:
```java
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);
}
}
```
4. Once defined, inject the same client elsewhere by name only:
```java
public class OrderService {
@Inject @Named("create-user")
private RestClient<CreateUserRequest, UserResponse> client;
}
```
## Service Registry Integration
When `service-registry` is on the classpath, URLs auto-resolve from the registry (no hard dependency):
```java
// 1. Explicit registry: prefix — always resolves from registry
@Endpoint(url = "registry:jwebmp-website")
@Named("jwebmp") private RestClient<Void, Response> client;
// 2. Bare service name — if registered, uses registry URL
@Endpoint(url = "jwebmp-website")
@Named("jwebmp") private RestClient<Void, Response> client;
// 3. Full URL — passes through unchanged
@Endpoint(url = "https://api.example.com/v1")
@Named("example") private RestClient<Void, Response> client;
```
Resolution logic in `RestClientRegistry.resolveUrl()`:
1. Resolves `${ENV_VAR}` placeholders first
2. If starts with `registry:` → resolves via `ServiceRegistry.resolve()`
3. If bare name (no `://`, no `/` prefix) → tries registry, falls back to original value
4. Uses reflection — no compile-time dependency on service-registry module
## Sending Requests
```java
client.send(); // no body
client.send(body); // with body
client.send(body, headers, queryParams); // with headers and query params
client.publish(body); // fire-and-forget (no response)
```
All methods return `Uni<Receive>`.
## Path Parameters
Use `{paramName}` placeholders in the endpoint URL:
```java
@Endpoint(url = "https://api.example.com/users/{userId}", method = "GET")
@Named("get-user")
private RestClient<Void, UserResponse> getUserClient;
// Usage
getUserClient.pathParam("userId", "123").send();
```
## Authentication
| Strategy | Annotation |
|---|---|
| Bearer/JWT | `@EndpointSecurity(value = SecurityType.Bearer, token = "${API_TOKEN}")` |
| Basic | `@EndpointSecurity(value = SecurityType.Basic, username = "user", password = "${PASSWORD}")` |
| API Key | `@EndpointSecurity(value = SecurityType.ApiKey, apiKey = "${API_KEY}", apiKeyHeader = "X-API-Key")` |
| OAuth2 | `@EndpointSecurity(value = SecurityType.OAuth2, oauth2TokenUrl = "...", oauth2ClientId = "...", oauth2ClientSecret = "${SECRET}")` |
| mTLS | `@EndpointSecurity(value = SecurityType.ClientCert, clientCertPath = "...", clientCertPassword = "${CERT_PASS}")` |
## Package-Level Endpoints
Declare a shared base URL on `package-info.java`:
```java
@Endpoint(url = "http://localhost:8080/api",
options = @EndpointOptions(readTimeout = 1000))
package com.example.api;
```
Field-level URLs starting with `/` are appended to the package-level base URL.
## Environment Variable Overrides
Every annotation attribute can be overridden via `REST_CLIENT_*` environment variables without code changes.
## Startup Flow
```
IGuiceContext.instance().inject()
└─ RestClientPreStartup (scans for @Endpoint-annotated fields)
└─ RestClientBinder (binds RestClient instances per @Named endpoint)
├─ RestClientRegistry (metadata: URL, types, security, options)
├─ WebClient cache (one per endpoint)
└─ RestClientConfigurator SPI (custom WebClientOptions)
```
## Non-Negotiable Constraints
- Client packages must `opens` to `com.google.guice` and `com.guicedee.rest.client`.
- DTO packages must `opens` to `com.fasterxml.jackson.databind`.
- Module must `requires transitive com.guicedee.rest.client;`.
- Only one `@Endpoint` field is needed per named endpoint; other classes inject by `@Named` alone.
- `RestClientConfigurator` SPI implementations must be dual-registered for tests.Related Skills
jwebmp-tsclient
TypeScript client generation for JWebMP plugins. Provides annotations and utilities for generating TypeScript interfaces, components, services, and modules from Java code. Supports @TsDependency, @TsDevDependency, @NgComponent, @NgDataService, @NgRestClient annotations. Use when creating JWebMP plugins that generate TypeScript code, defining npm dependencies, building Angular-integrated components, or generating typed Angular REST client services.
jwebmp-client
Client SPI library for JWebMP — defines AJAX pipeline contracts (AjaxCall/AjaxResponse), page contracts (IPage/IPageConfigurator), component model interfaces, and interceptor SPIs. Use when working with JWebMP client interfaces, AJAX interception, page configuration SPIs, component model interfaces, or extending JWebMP with custom interceptors and configurators.
guicedee-websockets
RFC 6455 WebSocket support for GuicedEE using Vert.x 5: call-scoped connections, action-based message routing via IWebSocketMessageReceiver SPI, group management and broadcasting, WebSocketServerOptions, and lifecycle hooks. Use when adding WebSocket messaging, implementing real-time communication, managing WebSocket groups, or creating message receivers.
guicedee-webservices
SOAP web services for GuicedEE using Apache CXF conventions: JAX-WS annotations (@WebService, @WebMethod, @WebParam, @WebResult), code-first and WSDL-first approaches, endpoint publishing, CXF interceptors and logging, MTOM, WS-Security (WSS4J), SOAP 1.1/1.2 bindings, and Guice DI integration. Use when creating SOAP services, publishing JAX-WS endpoints, configuring CXF bindings, or adding WS-Security.
guicedee-web
Bootstrap reactive HTTP/HTTPS servers with Vert.x 5 inside GuicedEE: Router setup, BodyHandler configuration, TLS/HTTPS, SPI extension points (VertxRouterConfigurator, VertxHttpServerOptionsConfigurator, VertxHttpServerConfigurator), per-verticle sub-routers, and environment-driven configuration. Use when setting up the Vert.x web server, configuring HTTP/HTTPS, adding custom routes or middleware, or managing server options.
guicedee-vertx
Build reactive services using Vert.x 5 inside the GuicedEE DI lifecycle: event-bus consumers, publishers, verticle deployment, codecs, throttling, clustering, SPI hooks, and JPMS module setup. Use when adding Vert.x event-bus messaging, deploying verticles, wiring reactive endpoints with Guice injection, configuring Vert.x runtime options, or implementing custom codecs and cluster managers.
guicedee-service-registry
Named service registry with health-aware resolution for GuicedEE. Register services by simple name, auto-construct URLs from cloud DNS suffix, monitor health status, resolve services via registry:name prefix or bare name in rest-client @Endpoint. Supports aliases, multiple external URLs, Kubernetes internal URLs, and per-service health paths. Use when registering named services, checking service health, resolving service URLs by name, or integrating with rest-client for service-to-service calls.
guicedee-rest
Build Jakarta REST (JAX-RS) services on Vert.x 5 inside GuicedEE: @Path/@GET/@POST route registration, parameter binding (@PathParam, @QueryParam, @HeaderParam, etc.), Guice-managed resource classes, response handling, content negotiation, and JPMS module setup. Use when creating REST endpoints, configuring Jakarta REST resources, or wiring JAX-RS services with Guice injection.
guicedee-rabbitmq
Annotation-driven RabbitMQ integration for GuicedEE with Vert.x 5: @RabbitConnectionOptions, @QueueExchange, @QueueDefinition, QueueConsumer/QueuePublisher injection, exchange management, queue options (priority, TTL, prefetch), publisher confirms, environment variable overrides, and verticle-scoped connections. Use when adding RabbitMQ messaging, declaring exchanges and queues, creating consumers and publishers, or configuring AMQP topology.
guicedee-persistence
Reactive JPA persistence with Hibernate Reactive 7, Vert.x 5 SQL clients, and Mutiny sessions inside GuicedEE: DatabaseModule setup, persistence.xml configuration, multi-database support, @EntityManager scoping, and environment variable resolution. Use when adding database persistence, configuring Hibernate Reactive, creating DatabaseModule subclasses, wiring Mutiny.SessionFactory, or managing multiple persistence units.
guicedee-openapi
Automatic OpenAPI 3.1 spec generation and serving for GuicedEE with Vert.x 5: scans Jakarta REST resources at startup, serves /openapi.json and /openapi.yaml endpoints, Swagger annotations support, @OpenAPIDefinition configuration, and companion Swagger UI module. Use when generating API documentation, serving OpenAPI specs, or configuring Swagger annotations on REST resources.
guicedee-metrics
Application metrics for GuicedEE using Vert.x 5 Dropwizard Metrics and MicroProfile Metrics 5.1: @Counted, @Timed, @MetricMethod annotations, Guice AOP interceptors, Prometheus scrape endpoint, Graphite reporting, JMX exposure, @MetricsOptions configuration, environment variable overrides, and Vert.x built-in metrics (event bus, HTTP, pools). Use when adding application metrics, configuring Prometheus endpoints, creating custom counters/timers, or monitoring Vert.x internals.