spring-boot-rest-api-standards_skill

Overview

This skill provides REST API design standards and best practices tailored for Spring Boot projects. It codifies resource-based URL patterns, HTTP method usage, status code conventions, DTO and validation patterns, error handling, pagination, security headers, and architecture guidance. Apply it when creating or reviewing controllers, DTOs, and API contracts to ensure consistency and production readiness.

How this skill works

The skill inspects API design choices and recommends concrete conventions: plural resource URLs, correct HTTP verbs, and standard status codes. It prescribes DTO separation from entities, Jakarta validation on request bodies, global exception handling via @RestControllerAdvice, Pageable-based pagination, and security header/CORS configuration. It also outlines layering, constructor injection, transaction management, logging, and API versioning to keep controllers thin and testable.

When to use it

• Designing new REST endpoints and routes
• Creating request/response DTOs and validation rules
• Implementing global error handling and exception mapping
• Adding pagination, filtering, and sorting to list endpoints
• Configuring security headers and CORS policies
• Reviewing API architecture, versioning, and production readiness

Best practices

• Use plural, resource-based URLs and version your API from the start (e.g., /v1/users).
• Use the correct HTTP methods and return appropriate status codes (201 for create, 204 for delete, 400 for validation).
• Separate API DTOs from domain entities; prefer immutable DTOs (records or @Value).
• Validate request bodies with @Valid and Jakarta constraints; handle MethodArgumentNotValidException centrally.
• Use @RestControllerAdvice to return standardized error responses with status, message, and path.
• Prefer constructor injection, keep controllers thin, and delegate business logic to services.

Example use cases

• Implement a CRUD users controller with Page responses and create/update DTOs.
• Design a paginated product listing with pageable parameters and total metadata.
• Add a global exception handler that converts validation and domain errors into consistent JSON errors.
• Review a microservice API for correct headers (CSP, X-Frame-Options) and proper CORS policy.
• Refactor a controller that currently exposes JPA entities to use DTOs and mapping.