Quarkus REST API Guidelines
Apply REST API design principles on Quarkus using Jakarta REST (JAX-RS).
What is covered in this Skill?
- Resource classes, @Path, HTTP method mapping, and resource URI design
- Status codes, Location headers, and Response building
- DTOs and Bean Validation at the boundary; ISO-8601 for date/time fields
- ExceptionMapper for consistent error JSON (RFC 7807 Problem Details)
- API versioning strategies (URI path, Accept header)
- Idempotency with Idempotency-Key header
- Optimistic concurrency: ETag, If-Match, If-None-Match
- HTTP caching with Cache-Control headers
- API deprecation: Sunset and Deprecation headers
- Pagination, sorting, and filtering query parameters
- Optional
/openapi via SmallRye; API-first contract maintained in openapi.yaml (codegen)
- Reactive vs blocking considerations; @RunOnVirtualThread
- Security integration at the filter layer
Scope: Apply recommendations based on the reference rules and good/bad code examples.
Constraints
Before applying REST changes, ensure the project compiles. After applying improvements, run full verification.
- MANDATORY: Run
./mvnw compile or mvn compile before applying any change
- PREREQUISITE: Project must compile before applying REST API improvements
- SAFETY: If compilation fails, stop immediately
- BLOCKING CONDITION: Compilation errors must be resolved by the user before proceeding
- VERIFY: Run
./mvnw clean verify or mvn clean verify after applying improvements
- BEFORE APPLYING: Read the reference for detailed rules and examples
When to use this skill
- 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
Workflow
- Read reference and assess project context
Read references/402-frameworks-quarkus-rest.md and inspect the current project setup before proposing changes.
- Gather scope and decide target improvements
Identify requested outcomes, constraints, and the minimum safe set of changes to apply.
- Apply framework-aligned changes
Implement or refactor configuration/code following the reference patterns and project conventions.
- Run verification and report results
Execute appropriate build/tests and summarize what changed, what was verified, and any follow-up actions.
Reference
For detailed guidance, examples, and constraints, see references/402-frameworks-quarkus-rest.md.
1---
2name: 402-frameworks-quarkus-rest
3description: 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, 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
4license: Apache-2.0
5metadata:
6 author: Juan Antonio Breña Moral
7 version: 0.18.0
8---
9
10# Quarkus REST API Guidelines
11
12Apply REST API design principles on Quarkus using Jakarta REST (JAX-RS).
13
14**What is covered in this Skill?**
15
16- Resource classes, @Path, HTTP method mapping, and resource URI design
17- Status codes, Location headers, and Response building
18- DTOs and Bean Validation at the boundary; ISO-8601 for date/time fields
19- ExceptionMapper for consistent error JSON (RFC 7807 Problem Details)
20- API versioning strategies (URI path, Accept header)
21- Idempotency with Idempotency-Key header
22- Optimistic concurrency: ETag, If-Match, If-None-Match
23- HTTP caching with Cache-Control headers
24- API deprecation: Sunset and Deprecation headers
25- Pagination, sorting, and filtering query parameters
26- Optional `/openapi` via SmallRye; API-first contract maintained in `openapi.yaml` (codegen)
27- Reactive vs blocking considerations; @RunOnVirtualThread
28- Security integration at the filter layer
29
30**Scope:** Apply recommendations based on the reference rules and good/bad code examples.
31
32## Constraints
33
34Before applying REST changes, ensure the project compiles. After applying improvements, run full verification.
35
36- **MANDATORY**: Run `./mvnw compile` or `mvn compile` before applying any change
37- **PREREQUISITE**: Project must compile before applying REST API improvements
38- **SAFETY**: If compilation fails, stop immediately
39- **BLOCKING CONDITION**: Compilation errors must be resolved by the user before proceeding
40- **VERIFY**: Run `./mvnw clean verify` or `mvn clean verify` after applying improvements
41- **BEFORE APPLYING**: Read the reference for detailed rules and examples
42
43## When to use this skill
44
45- Review or improve JAX-RS resources in a Quarkus project
46- Design HTTP APIs with validation and error handling on Quarkus
47- Add API versioning, idempotency, ETag concurrency, or deprecation headers
48- Implement pagination, sorting, or RFC 7807 Problem Details error responses
49- Improve Quarkus REST resources and exception mappers
50
51## Workflow
52
531. **Read reference and assess project context**
54
55Read `references/402-frameworks-quarkus-rest.md` and inspect the current project setup before proposing changes.
56
572. **Gather scope and decide target improvements**
58
59Identify requested outcomes, constraints, and the minimum safe set of changes to apply.
60
613. **Apply framework-aligned changes**
62
63Implement or refactor configuration/code following the reference patterns and project conventions.
64
654. **Run verification and report results**
66
67Execute appropriate build/tests and summarize what changed, what was verified, and any follow-up actions.
68
69## Reference
70
71For detailed guidance, examples, and constraints, see [references/402-frameworks-quarkus-rest.md](references/402-frameworks-quarkus-rest.md).
gabrielmoreira