jabrena/plinth / skills/402-frameworks-quarkus-rest
402-frameworks-quarkus-rest
VerifiedUse when you need to design, review, or improve REST APIs with Quarkus REST (Jakarta REST) — including resource classes, HTTP methods, status codes, request/response DTOs, Bean Validation, exception mappers, optional runtime OpenAPI exposure (SmallRye), contract-first generation from OpenAPI, content negotiation, pagination, sorting and filtering, API versioning, idempotency (Idempotency-Key), optimistic concurrency (ETag / If-Match), HTTP caching (Cache-Control), API deprecation (Sunset / Deprecation headers), RFC 7807 Problem Details, ISO-8601 for time in contracts, and security-aware boundaries. This should trigger for requests such as Review or improve JAX-RS resources in a Quarkus project; Design HTTP APIs with validation and error handling on Quarkus; Add API versioning, idempotency, ETag concurrency, or deprecation headers; Implement pagination, sorting, or RFC 7807 Problem Details error responses; Improve Quarkus REST resources and exception mappers. Part of Plinth Toolkit
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.8 KB |
| references/402-frameworks-quarkus-rest.md | markdown | 38.5 KB |
references/402-frameworks-quarkus-rest.md
View on GitHub---
name: 402-frameworks-quarkus-rest
description: Use when you need to design, review, or improve REST APIs with Quarkus REST (Jakarta REST) — including resource classes, HTTP methods, status codes, request/response DTOs, ISO-8601 instants in DTOs, Bean Validation, exception mappers, optional runtime OpenAPI exposure (SmallRye), contract-first generation from OpenAPI (Quarkus OpenAPI Generator or OpenAPI Generator `jaxrs-spec`), content negotiation, pagination, and security-aware boundaries.
license: Apache-2.0
metadata:
author: Juan Antonio Breña Moral
version: 0.19.0
---
# Quarkus REST API Guidelines
## Role
You are a Senior software engineer with extensive experience in REST API design and Quarkus
## Goal
Quarkus REST builds on Jakarta REST (`jakarta.ws.rs`). Resources should express clear HTTP semantics, validate input at the boundary, return appropriate status codes, and map failures to stable JSON (or Problem Details) without leaking stack traces. Use CDI-scoped resource classes (`@Path` + `@ApplicationScoped` or `@RequestScoped` as appropriate), inject services, and (if you need a live `/openapi` endpoint) expose SmallRye OpenAPI — for **API-first** work, the checked-in OpenAPI file is the contract, not annotation-heavy descriptions in code. Generate Jakarta REST API interfaces and models from the OpenAPI document using **Quarkus OpenAPI Generator** (`io.quarkiverse.openapi.generator:quarkus-openapi-generator`) or the **OpenAPI Generator** `jaxrs-spec` target with `interfaceOnly`, then implement those interfaces in CDI resource classes. Align with the same REST design principles as Spring (`@302-frameworks-spring-boot-rest`) while using JAX-RS annotations and Quarkus extensions.
## Constraints
Before applying any recommendations, ensure the project is in a valid state by running Maven compilation. Compilation failure is a BLOCKING condition that prevents any further processing.
- **MANDATORY**: Run `./mvnw compile` or `mvn compile` before applying any change
- **PREREQUISITE**: Project must compile successfully before any REST refactoring
- **CRITICAL SAFETY**: If compilation fails, IMMEDIATELY STOP and DO NOT CONTINUE
- **VERIFY**: Run `./mvnw clean verify` or `mvn clean verify` after applying improvements
- **BLOCKING CONDITION**: Compilation errors must be resolved by the user before proceeding with REST improvements
- **NO EXCEPTIONS**: Under no circumstances should REST API recommendations be applied to a project that fails to compile
## Examples
### Table of contents
- Example 1: CRUD resource
- Example 2: Request validation
- Example 3: Exception mapping
- Example 4: Resource URIs and naming
- Example 5: HTTP status codes
- Example 6: DTOs for requests and responses
- Example 7: Time and locale in contracts
- Example 8: API versioning
- Example 9: Structured error responses
- Example 10: Pagination, sorting, and filtering
- Example 11: Idempotency and safe retries
- Example 12: Optimistic concurrency with ETag
- Example 13: Caching semantics
- Example 14: Deprecation and sunset
- Example 15: Security annotations
- Example 16: API-first with OpenAPI Generator (Quarkus / Jakarta REST)
### Example 1: CRUD resource
Title: Jakarta REST with correct status codes
Description: Map operations to HTTP verbs and return `Response` when you need status codes and headers such as `Location`.
**Good example:**
```java
import jakarta.inject.Inject;
import jakarta.validation.Valid;
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
import java.net.URI;
import java.util.List;
@Path("/items")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class ItemResource {
private final ItemService items;
@Inject
public ItemResource(ItemService items) {
this.items = items;
}
@GET
public List<ItemResponse> list() {
return items.findAll();
}
@GET
@Path("{id}")
public ItemResponse get(@PathParam("id") long id) {
return items.findById(id);
}
@POST
public Response create(@Valid CreateItemRequest body) {
ItemResponse created = items.create(body);
return Response.created(URI.create("/items/" + created.id())).entity(created).build();
}
@DELETE
@Path("{id}")
public Response delete(@PathParam("id") long id) {
items.delete(id);
return Response.noContent().build();
}
}
```
**Bad example:**
```java
@Path("/api")
public class BadApi {
@GET
@Path("/deleteItem")
public String deleteViaGet(@QueryParam("id") String id) {
return "deleted"; // unsafe semantics — GET must not mutate
}
}
```
### Example 2: Request validation
Title: @Valid on request bodies
Description: Apply Bean Validation annotations on DTOs and `@Valid` on resource parameters so Quarkus returns **400** with violation details.
**Good example:**
```java
import jakarta.validation.Valid;
import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.NotBlank;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
public record RegisterRequest(
@NotBlank String name,
@NotBlank @Email String email
) { }
@Path("/users")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class UserResource {
@POST
public void register(@Valid RegisterRequest body) {
// persist
}
}
```
**Bad example:**
```java
@POST
public void register(RegisterRequest body) {
if (body.email() == null || !body.email().contains("@")) {
throw new IllegalArgumentException("bad email"); // ad-hoc validation — inconsistent 400 bodies
}
}
```
### Example 3: Exception mapping
Title: Consistent error JSON
Description: Register `ExceptionMapper` beans to translate domain exceptions into HTTP responses without duplicating try/catch in every resource method.
**Good example:**
```java
import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.ext.ExceptionMapper;
import jakarta.ws.rs.ext.Provider;
import java.util.Map;
@Provider
public class NotFoundMapper implements ExceptionMapper<NotFoundException> {
@Override
public Response toResponse(NotFoundException ex) {
return Response.status(404)
.entity(Map.of("error", ex.getMessage()))
.build();
}
}
```
**Bad example:**
```java
@GET
@Path("{id}")
public ItemResponse get(@PathParam("id") long id) {
try {
return service.find(id);
} catch (NotFoundException e) {
return null; // wrong — yields 200 with empty body or NPE
}
}
```
### Example 4: Resource URIs and naming
Title: Noun-based paths and hierarchy; no verbs in URIs
Description: Model resources as nouns with stable hierarchical paths. The HTTP method communicates the action; the path names the resource. Avoid RPC-style verbs (`/getAllOrders`, `/createOrder`) that duplicate what the HTTP verb already expresses.
**Good example:**
```text
GET /api/v1/orders
GET /api/v1/orders/{orderId}
GET /api/v1/orders/{orderId}/items
POST /api/v1/orders
PUT /api/v1/orders/{orderId}
PATCH /api/v1/orders/{orderId}/status
```
**Bad example:**
```text
GET /getAllOrders
GET /fetchOrderById?id={orderId}
POST /createNewOrder
GET /orderItems?orderId={orderId}
POST /processOrderCancellation
```
### Example 5: HTTP status codes
Title: 201 + Location for creates, 204 for deletes, 400/404/409 for errors
Description: Use status codes that match the real outcome: `201 Created` + `Location` for creates; `204 No Content` for successful deletes; `400` for input errors; `404` for missing resources; `409 Conflict` for state collisions. Never stuff errors into a `200 OK` body.
**Good example:**
```java
import jakarta.inject.Inject;
import jakarta.validation.Valid;
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
import java.net.URI;
@Path("/api/v1/orders")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class OrderResource {
private final OrderService service;
@Inject
public OrderResource(OrderService service) {
this.service = service;
}
@POST
public Response create(@Valid CreateOrderRequest body) {
OrderResponse created = service.create(body);
return Response.created(URI.create("/api/v1/orders/" + created.id()))
.entity(created).build(); // 201 Created + Location
}
@GET
@Path("{id}")
public OrderResponse get(@PathParam("id") long id) {
return service.findById(id); // 200 OK; 404 handled via ExceptionMapper
}
@DELETE
@Path("{id}")
public Response cancel(@PathParam("id") long id) {
service.cancel(id);
return Response.noContent().build(); // 204 No Content
}
}
```
**Bad example:**
```java
@Path("/orders")
public class BadOrderResource {
@POST
public String createOrder(CreateOrderRequest body) {
return "Order created"; // Bad: 200 instead of 201; no Location header
}
@GET
@Path("{id}")
public String get(@PathParam("id") long id) {
if (id == 0) {
return "{\"error\": \"not found\"}"; // Bad: stuffs error into 200 OK body
}
return "{}";
}
}
```
### Example 6: DTOs for requests and responses
Title: Decouple API contracts from persistence entities
Description: Expose records or DTOs from resources — never persistence entities — so serialization matches what clients should see. Returning entities directly leaks internal fields (password hashes, audit columns) and couples the API contract to the database schema.
**Good example:**
```java
import java.time.Instant;
// Persistence entity — never exposed directly to API consumers
class UserEntity {
long id;
String username;
String passwordHash; // internal — must never reach the client
String email;
Instant createdAt;
}
// Lean response DTO: no password hash, no internal audit fields
record UserResponse(long id, String username, String email, Instant createdAt) { }
// Inbound DTO: password accepted once, never echoed back
record CreateUserRequest(
@jakarta.validation.constraints.NotBlank String username,
@jakarta.validation.constraints.Email String email,
@jakarta.validation.constraints.Size(min = 8) String password) { }
```
**Bad example:**
```java
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;
@Path("/users")
@Produces(MediaType.APPLICATION_JSON)
public class UserResource {
@GET
@Path("{id}")
public UserEntity get(@PathParam("id") long id) {
return findById(id); // Bad: exposes passwordHash, audit columns, and all internal state
}
private UserEntity findById(long id) { return new UserEntity(); }
}
class UserEntity {
public long id;
public String username;
public String passwordHash; // leaked to every API consumer
}
```
### Example 7: Time and locale in contracts
Title: ISO-8601 with offset; optional `Accept-Language` for errors
Description: Model timestamps as `Instant` or `OffsetDateTime` (ISO-8601 with offset) so clients interpret wall-clock unambiguously—avoid legacy `Date` and ambiguous zone-less `LocalDateTime` in public JSON unless the domain is strictly calendar-local. For localized problem/error text (RFC 7807-style bodies), honor `Accept-Language` only if you keep stable problem `type` URIs/codes identical across locales and avoid leaking sensitive details through translated messages.
**Good example:**
```java
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.Context;
import jakarta.ws.rs.core.HttpHeaders;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.ext.ExceptionMapper;
import jakarta.ws.rs.ext.Provider;
import java.time.Instant;
import java.time.OffsetDateTime;
import java.time.ZoneOffset;
import java.util.Locale;
import java.util.ResourceBundle;
@Path("/api/v1/events")
@Produces(MediaType.APPLICATION_JSON)
public class EventResource {
@GET
@Path("{id}")
public Response get(@PathParam("id") String id) {
return Response.ok(new EventDTO(
Instant.parse("2026-03-23T12:00:00Z"),
OffsetDateTime.of(2026, 3, 23, 13, 0, 0, 0, ZoneOffset.ofHours(1)))).build();
}
}
record EventDTO(Instant occurredAt, OffsetDateTime windowStart) { }
// Same Problem Detail field shape as in structured error examples — title/detail from bundles, never raw ex.getMessage()
record ProblemDetail(String type, String title, int status, String detail, String errorId) { }
@Provider
public class IllegalArgumentExceptionMapper implements ExceptionMapper<IllegalArgumentException> {
@Context
HttpHeaders headers;
@Override
public Response toResponse(IllegalArgumentException ex) {
Locale locale = headers.getAcceptableLanguages().isEmpty()
? Locale.ENGLISH
: headers.getAcceptableLanguages().getFirst();
ResourceBundle bundle = ResourceBundle.getBundle("ProblemMessages", locale);
String detail = bundle.getString("problem.invalid_argument.detail");
String title = bundle.getString("problem.invalid_argument.title");
return Response.status(400)
.type(MediaType.APPLICATION_JSON)
.entity(new ProblemDetail(
"https://example.com/problems/invalid-argument",
title,
400,
detail,
null))
.build();
}
}
```
**Bad example:**
```java
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
import java.util.Date;
@Path("/events")
@Produces(MediaType.APPLICATION_JSON)
public class AmbiguousTimeResource {
@GET
@Path("{id}")
public Response get(@PathParam("id") String id) {
return Response.ok(new EventDTO(new Date())).build();
}
}
class EventDTO {
private Date createdAt;
EventDTO(Date createdAt) { this.createdAt = createdAt; }
}
```
### Example 8: API versioning
Title: URI path, custom header, or vendor media type — pick one and apply uniformly
Description: Introduce versioning early so breaking changes do not silently affect existing clients. Pick one strategy and apply it **uniformly** across every resource. Common options: **URI path** (`/api/v1/…`) — easiest to browse, cache, and test; visible in logs. **Custom header** (`X-API-Version: 2`) — clean URIs; version not in browser or CDN cache keys. **Vendor media type** (`Accept: application/vnd.example.order+json;version=2`) — RESTful negotiation; higher client complexity.
**Good example:**
```java
// ── Strategy 1: URI path versioning ──────────────────────────────────────────
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;
@Path("/api/v1/orders")
@Produces(MediaType.APPLICATION_JSON)
public class OrderResourceV1 {
@GET
@Path("{id}")
public OrderDTOv1 get(@PathParam("id") long id) {
return new OrderDTOv1(id, "PENDING");
}
}
// V2 route — breaking shape change isolated behind a new path
@Path("/api/v2/orders")
@Produces(MediaType.APPLICATION_JSON)
public class OrderResourceV2 {
@GET
@Path("{id}")
public OrderDTOv2 get(@PathParam("id") long id) {
return new OrderDTOv2(id, "PENDING", java.time.Instant.now());
}
}
record OrderDTOv1(long id, String status) { }
record OrderDTOv2(long id, String status, java.time.Instant createdAt) { }
```
**Bad example:**
```java
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;
// No versioning — any breaking change silently breaks all clients
@Path("/orders")
@Produces(MediaType.APPLICATION_JSON)
public class UnversionedOrderResource {
@GET
@Path("{id}")
public OrderDTO get(@PathParam("id") long id) {
return new OrderDTO(id);
}
}
record OrderDTO(long id) { }
```
### Example 9: Structured error responses
Title: ExceptionMapper with RFC 7807 Problem Detail shape; no stack traces to clients
Description: Register `ExceptionMapper` beans to centralize error handling. Return a consistent JSON body with stable fields (type, title, status, detail) aligned with RFC 7807 Problem Details. Log full exceptions server-side with a correlation ID; never return stack traces or raw exception messages to API clients in production.
**Good example:**
```java
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.ext.ExceptionMapper;
import jakarta.ws.rs.ext.Provider;
import java.util.UUID;
import org.jboss.logging.Logger;
public record ProblemDetail(String type, String title, int status, String detail, String errorId) { }
// Domain exception hierarchy — one mapper handles the family
public abstract class DomainException extends RuntimeException {
protected DomainException(String message) { super(message); }
public abstract int httpStatus();
public abstract String typeSlug();
public abstract String title();
}
public class NotFoundException extends DomainException {
public NotFoundException(String message) { super(message); }
public int httpStatus() { return 404; }
public String typeSlug() { return "not-found"; }
public String title() { return "Resource Not Found"; }
}
@Provider
public class DomainExceptionMapper implements ExceptionMapper<DomainException> {
@Override
public Response toResponse(DomainException ex) {
return Response.status(ex.httpStatus())
.type(MediaType.APPLICATION_JSON)
.entity(new ProblemDetail(
"https://example.com/problems/" + ex.typeSlug(),
ex.title(),
ex.httpStatus(),
ex.getMessage(),
null))
.build();
}
}
@Provider
public class GlobalExceptionMapper implements ExceptionMapper<Exception> {
private static final Logger LOG = Logger.getLogger(GlobalExceptionMapper.class);
@Override
public Response toResponse(Exception ex) {
String errorId = UUID.randomUUID().toString();
LOG.errorf(ex, "Unhandled exception [%s]", errorId);
return Response.serverError()
.type(MediaType.APPLICATION_JSON)
.entity(new ProblemDetail(
"https://example.com/problems/internal-error",
"Internal Server Error",
500,
"An unexpected error occurred.",
errorId))
.build();
}
}
```
**Bad example:**
```java
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
@Path("/orders")
@Produces(MediaType.APPLICATION_JSON)
public class OrderResource {
@GET
@Path("{id}")
public Response get(@PathParam("id") long id) {
try {
return Response.ok(findOrder(id)).build();
} catch (Exception e) {
// Bad: leaks stack trace and exception type to clients
return Response.serverError()
.entity(e.toString()) // internal details exposed
.build();
}
}
private Object findOrder(long id) { throw new RuntimeException("DB unavailable"); }
}
```
### Example 10: Pagination, sorting, and filtering
Title: Bounded pages, sort whitelist, optional Link headers (RFC 8288)
Description: Returning unbounded lists does not scale. Use explicit `page`/`size` query params with server-enforced maximums, whitelist sortable field names, and optionally emit `Link` headers (`rel="next"` / `rel="prev"`) for discoverable navigation (RFC 8288).
**Good example:**
```java
import jakarta.inject.Inject;
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
import java.util.List;
import java.util.Set;
@Path("/api/v1/orders")
@Produces(MediaType.APPLICATION_JSON)
public class OrderListResource {
private static final int MAX_PAGE_SIZE = 100;
private static final Set<String> ALLOWED_SORT = Set.of("createdAt", "status", "total");
private final OrderService service;
@Inject
public OrderListResource(OrderService service) {
this.service = service;
}
@GET
public Response list(
@QueryParam("page") @DefaultValue("0") int page,
@QueryParam("size") @DefaultValue("20") int size,
@QueryParam("sort") @DefaultValue("createdAt") String sort) {
if (size > MAX_PAGE_SIZE) {
throw new BadRequestException("size exceeds maximum of " + MAX_PAGE_SIZE);
}
if (!ALLOWED_SORT.contains(sort)) {
throw new BadRequestException("sort by '" + sort + "' is not allowed");
}
List<OrderResponse> orders = service.findPage(page, size, sort);
String nextLink = "</api/v1/orders?page=" + (page + 1) + "&size=" + size + ">; rel=\"next\"";
return Response.ok(orders).header("Link", nextLink).build();
}
}
record OrderResponse(long id, String status) { }
interface OrderService { List<OrderResponse> findPage(int page, int size, String sort); }
```
**Bad example:**
```java
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;
import java.util.List;
@Path("/orders")
@Produces(MediaType.APPLICATION_JSON)
public class UnboundedOrderResource {
@GET
public List<OrderResponse> listAll(@QueryParam("sort") String sort) {
// Bad: no result cap — dumps entire table; sort field not validated
return loadAllOrders(sort);
}
private List<OrderResponse> loadAllOrders(String sort) { return List.of(); }
}
record OrderResponse(long id, String status) { }
```
### Example 11: Idempotency and safe retries
Title: Idempotency-Key header, deduplication, 409 Conflict
Description: Network clients retry `POST`; without idempotency, creates can duplicate. Accept an `Idempotency-Key` header and return the same result when the key replays a completed operation. Return **409 Conflict** when a request collides with current resource state (e.g. duplicate business key).
**Good example:**
```java
import jakarta.inject.Inject;
import jakarta.validation.Valid;
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
import java.net.URI;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
import org.eclipse.microprofile.openapi.annotations.Operation;
import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
@Path("/api/v1/payments")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class PaymentResource {
private final Map<String, PaymentResponse> completed = new ConcurrentHashMap<>();
@Operation(summary = "Create payment",
description = "Idempotent: repeating the same Idempotency-Key returns the original result without a double charge.")
@POST
public Response create(
@Parameter(description = "Client-generated deduplication key", required = true)
@HeaderParam("Idempotency-Key") String idempotencyKey,
@Valid CreatePaymentRequest body) {
if (idempotencyKey == null || idempotencyKey.isBlank()) {
throw new BadRequestException("Idempotency-Key header is required");
}
PaymentResponse prior = completed.get(idempotencyKey);
if (prior != null) {
return Response.ok(prior).build(); // replay — no double charge
}
PaymentResponse created = new PaymentResponse("pay-" + System.currentTimeMillis());
completed.put(idempotencyKey, created);
return Response.created(URI.create("/api/v1/payments/" + created.id()))
.entity(created).build();
}
}
record CreatePaymentRequest(String accountId, int amountCents) { }
record PaymentResponse(String id) { }
```
**Bad example:**
```java
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
@Path("/payments")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class NonIdempotentPaymentResource {
@POST
public Response charge(CreatePaymentRequest body) {
// Bad: no Idempotency-Key — every retry causes a duplicate charge
return Response.ok(new PaymentResponse("pay-new")).build();
}
}
record CreatePaymentRequest(String accountId, int amountCents) { }
record PaymentResponse(String id) { }
```
### Example 12: Optimistic concurrency with ETag
Title: If-Match / If-None-Match, 412 Precondition Failed, 304 Not Modified
Description: Prevent lost updates by generating an `ETag` on reads and requiring `If-Match` on writes. Use `jakarta.ws.rs.core.Request.evaluatePreconditions()` to check `If-None-Match` (yields **304**) or `If-Match` (yields **412**) without manual boilerplate.
**Good example:**
```java
import jakarta.inject.Inject;
import jakarta.validation.Valid;
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.*;
@Path("/api/v1/items")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class ItemResource {
private final ItemService service;
@Inject
public ItemResource(ItemService service) {
this.service = service;
}
@GET
@Path("{id}")
public Response get(@PathParam("id") long id, @Context Request request) {
ItemResponse item = service.findById(id);
EntityTag etag = new EntityTag(Integer.toHexString(item.version()));
Response.ResponseBuilder notModified = request.evaluatePreconditions(etag);
if (notModified != null) {
return notModified.build(); // 304 Not Modified
}
return Response.ok(item).tag(etag).build();
}
@PUT
@Path("{id}")
public Response update(@PathParam("id") long id,
@HeaderParam("If-Match") String ifMatch,
@Valid UpdateItemRequest body) {
ItemResponse current = service.findById(id);
EntityTag etag = new EntityTag(Integer.toHexString(current.version()));
if (!etag.toString().equals(ifMatch)) {
return Response.status(Response.Status.PRECONDITION_FAILED).build(); // 412
}
ItemResponse updated = service.update(id, body);
return Response.ok(updated)
.tag(new EntityTag(Integer.toHexString(updated.version()))).build();
}
}
record ItemResponse(long id, String name, int version) { }
record UpdateItemRequest(String name) { }
interface ItemService {
ItemResponse findById(long id);
ItemResponse update(long id, UpdateItemRequest req);
}
```
**Bad example:**
```java
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
@Path("/items")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class BlindOverwriteResource {
@PUT
@Path("{id}")
public Response update(@PathParam("id") long id, UpdateItemRequest body) {
// Bad: no ETag / version check — concurrent updates silently overwrite each other
return Response.ok(new ItemResponse(id, body.name(), 0)).build();
}
}
record UpdateItemRequest(String name) { }
record ItemResponse(long id, String name, int version) { }
```
### Example 13: Caching semantics
Title: Cache-Control: public for catalog data, no-store for authenticated responses
Description: Set `Cache-Control` deliberately: `public, max-age=N` for anonymous catalog data so CDNs and browsers can cache it; `no-store` for authenticated or personalized payloads to prevent cross-user data leaks via shared caches.
**Good example:**
```java
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.CacheControl;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
@Path("/api/v1/catalog")
@Produces(MediaType.APPLICATION_JSON)
public class CatalogResource {
@GET
@Path("{id}")
public Response getPublic(@PathParam("id") long id) {
CacheControl cc = new CacheControl();
cc.setMaxAge(300);
return Response.ok(new ProductResponse(id, "Widget"))
.cacheControl(cc)
.header("Cache-Control", "public, max-age=300") // mark as publicly cacheable
.build();
}
}
@Path("/api/v1/me")
@Produces(MediaType.APPLICATION_JSON)
public class ProfileResource {
@GET
public Response getProfile() {
CacheControl noStore = new CacheControl();
noStore.setNoStore(true);
return Response.ok(new UserProfile("alice@example.com"))
.cacheControl(noStore)
.build(); // no-store: never served from a shared cache
}
}
record ProductResponse(long id, String name) { }
record UserProfile(String email) { }
```
**Bad example:**
```java
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
@Path("/api/me")
@Produces(MediaType.APPLICATION_JSON)
public class BadProfileResource {
@GET
public Response getProfile() {
// Bad: authenticated user profile marked as publicly cacheable
// A CDN will serve user A's data to user B on the next request
return Response.ok(new UserProfile("alice@example.com"))
.header("Cache-Control", "public, max-age=3600")
.build();
}
}
record UserProfile(String email) { }
```
### Example 14: Deprecation and sunset
Title: Deprecation, Sunset, and Link headers for API lifecycle signalling
Description: When an endpoint or version is headed for removal, advertise it with RFC-style headers: `Deprecation` (`true` or an HTTP-date timestamp), `Sunset` with the expected removal date, and `Link` (`rel="successor-version"`) pointing to the replacement. Pair with your versioning strategy and document the timeline in OpenAPI.
**Good example:**
```java
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
@Path("/api/v1/orders")
@Produces(MediaType.APPLICATION_JSON)
public class DeprecatedOrderResourceV1 {
@GET
@Path("{id}")
public Response get(@PathParam("id") long id) {
return Response.ok(new OrderDTOv1(id, "PENDING"))
.header("Deprecation", "true")
.header("Sunset", "Sat, 31 Dec 2026 23:59:59 GMT")
.header("Link", "</api/v2/orders/" + id + ">; rel=\"successor-version\"")
.build();
// Production tip: emit Deprecation/Sunset from a ContainerResponseFilter
// so all deprecated resources are flagged uniformly without per-method repetition.
}
}
record OrderDTOv1(long id, String status) { }
```
**Bad example:**
```java
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
// No Deprecation / Sunset headers — clients have no way to know this endpoint is being removed
@Path("/api/v1/orders")
@Produces(MediaType.APPLICATION_JSON)
public class SilentBreakResource {
@GET
@Path("{id}")
public Response get(@PathParam("id") long id) {
return Response.ok(new OrderDTOv1(id, "PENDING")).build();
}
}
record OrderDTOv1(long id, String status) { }
```
### Example 15: Security annotations
Title: @RolesAllowed, @Authenticated, and @PermitAll for declarative access control
Description: Use Jakarta Security and Quarkus Security annotations to declare access control at the resource or method level. Prefer `@RolesAllowed` for role-based access, `@io.quarkus.security.Authenticated` for any authenticated user, and `@PermitAll` for public endpoints. Avoid ad-hoc security checks inside business logic.
**Good example:**
```java
import io.quarkus.security.Authenticated;
import jakarta.annotation.security.PermitAll;
import jakarta.annotation.security.RolesAllowed;
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
import java.util.List;
@Path("/api/v1/orders")
@Produces(MediaType.APPLICATION_JSON)
@Authenticated // all methods require authentication unless overridden
public class SecureOrderResource {
@GET
@PermitAll // public catalog read — no auth required
public List<OrderResponse> listPublic() {
return List.of();
}
@GET
@Path("{id}")
// @Authenticated inherited — any authenticated user can read
public OrderResponse get(@PathParam("id") long id) {
return new OrderResponse(id, "PENDING");
}
@DELETE
@Path("{id}")
@RolesAllowed("admin") // only users with the admin role can delete
public Response delete(@PathParam("id") long id) {
return Response.noContent().build();
}
}
record OrderResponse(long id, String status) { }
```
**Bad example:**
```java
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.*;
@Path("/orders")
@Produces(MediaType.APPLICATION_JSON)
public class AdHocSecurityResource {
@DELETE
@Path("{id}")
public Response delete(@PathParam("id") long id, @Context HttpHeaders headers) {
// Bad: manual token inspection instead of declarative security annotations
String token = headers.getHeaderString("X-Admin-Token");
if (!"secret".equals(token)) {
return Response.status(403).build();
}
return Response.noContent().build();
}
}
```
### Example 16: API-first with OpenAPI Generator (Quarkus / Jakarta REST)
Title: Generate JAX-RS API interfaces from `openapi.yaml`; implement as `@Path` resources
Description: Store the contract under `src/main/resources/openapi` (or similar) and generate **Jakarta REST** API interfaces plus models in the build. Prefer **Quarkus OpenAPI Generator** (`quarkus-openapi-generator`) for Quarkus-native integration, or **`openapi-generator-maven-plugin`** with `generatorName` `jaxrs-spec`, `interfaceOnly=true`, and `useJakartaEe=true`. The generated `*Api` types declare `@Path`, `@GET`/`@POST`, `@Consumes`/`@Produces`; your CDI resource class **implements** the interface and delegates to application services. Register `ExceptionMapper` as needed. Keep the OpenAPI spec authoritative in CI (lint before merge); generated interfaces carry the contract — avoid duplicating it with inline MicroProfile OpenAPI annotations unless you intentionally maintain runtime OpenAPI exposure separately.
**Good example:**
```text
<!-- Option A: Quarkus extension — see Quarkus OpenAPI Generator guide for full config -->
<!--
<dependency>
<groupId>io.quarkiverse.openapi.generator</groupId>
<artifactId>quarkus-openapi-generator-server</artifactId>
</dependency>
-->
<!-- Option B: openapi-generator-maven-plugin (jaxrs-spec) -->
<plugin>
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>${openapi-generator.version}</version>
<executions>
<execution>
<goals><goal>generate</goal></goals>
<configuration>
<inputSpec>${project.basedir}/src/main/resources/openapi/api.yaml</inputSpec>
<generatorName>jaxrs-spec</generatorName>
<apiPackage>com.example.generated.api</apiPackage>
<modelPackage>com.example.generated.model</modelPackage>
<configOptions>
<interfaceOnly>true</interfaceOnly>
<useJakartaEe>true</useJakartaEe>
<supportAsync>true</supportAsync>
</configOptions>
</configuration>
</execution>
</executions>
</plugin>
// --- Implement generated UsersApi as a CDI resource ---
import com.example.generated.api.UsersApi;
import com.example.generated.model.UserDto;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import jakarta.ws.rs.Path;
@ApplicationScoped
@Path("/api/v1")
public class UserResource implements UsersApi {
private final UserService users;
@Inject
public UserResource(UserService users) {
this.users = users;
}
@Override
public UserDto getUserById(String userId) {
return users.require(userId);
}
}
interface UserService {
UserDto require(String id);
}
```
**Bad example:**
```java
// Anti-pattern: resource paths and payloads edited only in Java while openapi.yaml
// is stale — contract tests and client SDKs disagree with runtime behavior.
@jakarta.ws.rs.Path("/api/v1")
public class DriftResource {
@jakarta.ws.rs.GET
@jakarta.ws.rs.Path("users/{id}")
public Object get(String id) {
return id;
}
}
```
## Output Format
- **ANALYZE** resources for HTTP misuse, URI shape, status codes, DTO boundaries, versioning, deprecation/sunset/Link headers, `@Produces`/`@Consumes` declarations, ISO-8601 time fields, pagination bounds, Bean Validation on request DTOs, idempotency, ETag/concurrency, Cache-Control correctness, ExceptionMapper coverage, security annotations, and (when API-first) consistency between `openapi.yaml` and generated Jakarta REST API interfaces vs resource implementations
- **CATEGORIZE** findings by impact (CRITICAL for security/semantic violations, MAINTAINABILITY for DTO/versioning/docs, CONSISTENCY for errors) and by area (routing, responses, errors, security, caching, docs)
- **APPLY** improvements: fix unsafe GETs, normalize paths, return correct status codes, introduce DTO boundaries, use `OffsetDateTime`/`Instant` in API DTOs for ISO-8601 time fields, add versioning, emit deprecation/sunset/Link when phasing out endpoints, tighten `@Produces`/`@Consumes`, bound list endpoints with `page`/`size` caps, add `@Valid` on request bodies, add idempotency and 409 Conflict patterns, add ETag/`If-Match` checks for updates, set `Cache-Control`, centralize errors with `ExceptionMapper` and Problem Detail shape, add declarative security annotations, and (API-first) align CDI resources with generated `*Api` interfaces from the checked-in `openapi.yaml`
- **IMPLEMENT** incrementally: preserve public API contracts where possible; use deprecation and versioning for breaking changes; keep error shapes backward compatible unless versioning allows a break
- **EXPLAIN** trade-offs (e.g., URI vs header versioning, blocking vs reactive patterns, `@Blocking` vs `@RunOnVirtualThread`) when multiple valid options exist
- **VALIDATE** with `./mvnw compile` before and `./mvnw clean verify` after substantive edits; exercise critical endpoints in integration tests where available
## Safeguards
- **BLOCKING SAFETY CHECK**: ALWAYS run `./mvnw compile` or `mvn compile` before ANY REST refactoring — compilation failure is a HARD STOP
- **CRITICAL VALIDATION**: Run `./mvnw clean verify` after changes that touch resources, exception mappers, security, or DTOs
- **SECURITY**: Never log or return secrets, tokens, or passwords in API responses; verify that error payloads do not include stack traces in production
- **COMPATIBILITY**: Changing status codes, DTO field names, or error JSON shapes can break clients — coordinate versioning or deprecation before making breaking changes
- **REACTIVE THREADS**: Long blocking JDBC or HTTP client calls on the Vert.x event loop will stall other requests — annotate with `@Blocking` or use `@RunOnVirtualThread`
- **INCREMENTAL SAFETY**: Prefer small, reviewable resource and mapper changes over large sweeping rewrites; verify compile and tests between stepsRelated skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |