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