Agent skill

spring-boot-web-api

Spring Boot 4 REST API implementation patterns. Use when creating REST controllers, REST endpoints, request validation, exception handlers with ProblemDetail (RFC 9457), API versioning, content negotiation, WebFlux reactive endpoints, HTTP clients with @HttpExchange, JSON serialization with Jackson 3, error handling, or CORS configuration. Covers @RestController patterns, Bean Validation 3.1, global error handling, and declarative HTTP clients.

View SKILL.md on GitHub Repository
Stars 9
Forks 1

Install this agent skill to your Project

npx add-skill https://github.com/joaquimscosta/arkhe-claude-plugins/tree/main/plugins/spring-boot/skills/spring-boot-web-api

SKILL.md

Spring Boot Web API Layer

REST API implementation patterns for Spring Boot 4 with Spring MVC and WebFlux.

Technology Selection

Choose When
Spring MVC JPA/JDBC backend, simpler debugging, team knows imperative style
Spring WebFlux High concurrency (10k+ connections), streaming, reactive DB (R2DBC)

With Virtual Threads (Java 21+), MVC handles high concurrency without WebFlux complexity.

Core Workflow

  1. Create controller → 2. Define endpoints → 3. Add validation → 4. Handle exceptions → 5. Configure versioning

See WORKFLOW.md for detailed step-by-step instructions with code examples.

Quick Patterns

See EXAMPLES.md for complete working examples including:

  • REST Controller with CRUD operations and pagination (Java + Kotlin)
  • Request/Response DTOs with Bean Validation 3.1
  • Global Exception Handler using ProblemDetail (RFC 9457)
  • Native API Versioning with header configuration
  • Jackson 3 Configuration for custom serialization
  • Controller Testing with @WebMvcTest

Spring Boot 4 Specifics

  • Jackson 3 uses tools.jackson package (not com.fasterxml.jackson)
  • ProblemDetail enabled by default: spring.mvc.problemdetails.enabled=true
  • API Versioning via version attribute in mapping annotations
  • @MockitoBean replaces @MockBean in tests
  • @HttpExchange declarative HTTP clients (replaces RestTemplate patterns)
  • RestTestClient new fluent API for testing REST endpoints

@HttpExchange Declarative Client (Spring 7)

New declarative HTTP client interface (alternative to RestTemplate/WebClient):

java
@HttpExchange(url = "/users", accept = "application/json")
public interface UserClient {

    @GetExchange("/{id}")
    User getUser(@PathVariable Long id);

    @PostExchange
    User createUser(@RequestBody CreateUserRequest request);

    @DeleteExchange("/{id}")
    void deleteUser(@PathVariable Long id);
}

// Configuration
@Configuration
class ClientConfig {
    @Bean
    UserClient userClient(RestClient.Builder builder) {
        RestClient restClient = builder.baseUrl("https://api.example.com").build();
        return HttpServiceProxyFactory
            .builderFor(RestClientAdapter.create(restClient))
            .build()
            .createClient(UserClient.class);
    }
}

Benefits: Type-safe, annotation-driven, works with both RestClient and WebClient.

Detailed References

  • Workflow: See WORKFLOW.md for detailed step-by-step web API implementation
  • Examples: See EXAMPLES.md for complete working code examples
  • Troubleshooting: See TROUBLESHOOTING.md for common issues and Boot 4 migration
  • Controllers & Validation: See references/CONTROLLERS.md for validation groups, custom validators, content negotiation
  • Error Handling: See references/ERROR-HANDLING.md for ProblemDetail patterns, exception hierarchy
  • WebFlux Patterns: See references/WEBFLUX.md for reactive endpoints, functional routers, WebTestClient

Related Skills

Need Skill
DDD concepts domain-driven-design
Data layer for DTOs spring-boot-data-ddd
Controller testing spring-boot-testing
API security spring-boot-security

Anti-Pattern Checklist

Anti-Pattern Fix
Business logic in controllers Delegate to application services
Returning entities directly Convert to DTOs
Generic error messages Use typed ProblemDetail with error URIs
Missing validation Add @Valid on @RequestBody
Blocking calls in WebFlux Use reactive operators only
Catching exceptions silently Let propagate to @RestControllerAdvice

Critical Reminders

  1. Controllers are thin — Delegate to services, no business logic
  2. Validate at the boundary — @Valid on all request bodies
  3. Use ProblemDetail — Structured errors for all exceptions
  4. Version from day one — Easier than retrofitting
  5. @MockitoBean not @MockBean — Spring Boot 4 change

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

joaquimscosta/arkhe-claude-plugins

Skill Name

What this skill does. Use when user mentions "keyword1", "keyword2", or "keyword3". Keep under 1,024 characters and include specific trigger keywords.

9 1
Explore
joaquimscosta/arkhe-claude-plugins

plugin-release-checker

9 1
Explore
joaquimscosta/arkhe-claude-plugins

skill-validator

Validate skills against Anthropic best practices for frontmatter, structure, content, file organization, hooks, MCP, and security (62 rules in 8 categories). Use when creating new skills, updating existing skills, before publishing skills, reviewing skill quality, or when user mentions "validate skill", "check skill", "skill best practices", "skill review", or "lint skill".

9 1
Explore
joaquimscosta/arkhe-claude-plugins

sync-docs

Sync official Anthropic documentation and analyze impact on project components. Runs docs/reference/update-claude-docs.sh, computes diffs, and reports impacts on the skill validator, plugins, and project documentation. Use when user mentions "sync docs", "update reference docs", "refresh docs", or "check doc changes".

9 1
Explore
joaquimscosta/arkhe-claude-plugins

research-frontmatter

Enforce standard YAML frontmatter on research documents in docs/research/. Use when creating, editing, or promoting research files, when user mentions "research metadata", "research frontmatter", or "research staleness".

9 1
Explore
joaquimscosta/arkhe-claude-plugins

deep-research

Deep research on technical topics using EXA tools with intelligent two-tier caching. Use when user asks to research a topic, investigate best practices, look up information, find patterns, or explore architectures. Also invoked by /research command. Triggers: "research", "look up", "investigate", "deep dive", "find information about", "what are best practices for", "how do others implement".

9 1
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results