Cursor-rules-java 302-frameworks-spring-boot-rest

Use when you need to design, review, or improve REST APIs with Spring Boot — including HTTP methods, resource URIs, status codes, DTOs, versioning, deprecation and sunset headers, content negotiation (JSON and vendor media types), ISO-8601 instants in DTOs, pagination/sorting/filtering, Bean Validation at the boundary, idempotency, ETag concurrency, HTTP caching, error handling, security, contract-first OpenAPI (OpenAPI Generator), controller advice, and problem details for errors. Part of the skills-for-java project

install

source · Clone the upstream repo

git clone https://github.com/jabrena/cursor-rules-java

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/jabrena/cursor-rules-java "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/302-frameworks-spring-boot-rest" ~/.claude/skills/jabrena-cursor-rules-java-302-frameworks-spring-boot-rest && rm -rf "$T"

manifest: skills/302-frameworks-spring-boot-rest/SKILL.md

Java REST API Design Principles

Apply REST API design principles for Spring Boot applications.

What is covered in this Skill?

HTTP methods (GET, POST, PUT, PATCH, DELETE) — semantic consistency
Resource URI design
HTTP status codes
Request/response DTOs with lean contracts
API versioning (URI, header, or media type — applied consistently)
Bean Validation at the boundary (@Valid/@Validated on controller inputs, 400 on failure)
Pagination, sorting, and filtering (Page/Pageable with caps)
ISO-8601 instants with offset (OffsetDateTime, Instant) in JSON contracts
Content negotiation (JSON default; vendor media types when meaningful)
Idempotency-Key support for POST creates; 409 Conflict for collisions
ETag concurrency with If-Match/If-None-Match; 412 Precondition Failed / 304 Not Modified
HTTP caching discipline (Cache-Control, ETag, Last-Modified)
Deprecation and sunset headers (Deprecation, Sunset, Link rel="successor-version")
Error handling
API security (TLS, authentication, authorization, input validation)
API contract: OpenAPI file as source of truth for API-first (OpenAPI Generator)
Controller advice and problem details (RFC 7807)

Scope: Apply recommendations based on the reference rules and good/bad code examples.

Constraints

Before applying any REST API changes, ensure the project compiles. If compilation fails, stop immediately. After applying improvements, run full verification.

MANDATORY: Run
```
./mvnw compile
```
or
```
mvn compile
```
before applying any change
SAFETY: If compilation fails, stop immediately
VERIFY: Run
```
./mvnw clean verify
```
or
```
mvn clean verify
```
after applying improvements
BEFORE APPLYING: Read the reference for detailed rules and good/bad patterns

When to use this skill

Review Java code for Spring Boot REST API
Apply best practices for Spring Boot REST API in Java code

Reference

For detailed guidance, examples, and constraints, see references/302-frameworks-spring-boot-rest.md.