api-versioning
/api-versioning
Use when versioning Spring MVC or WebFlux APIs in Spring Boot 3 / Spring Framework 6. Covers explicit URL, header, and media-type strategies, compatibility rules, and deprecation handling.
- Author
- rrezartprebreza ↗
- Repository
- spring-boot-skills ↗
- Licence
- MIT
- Last repository change
- 22.10.2026
Assessment and security
- Files in this package
- 4
- Scripts
- 2
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 2 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: examples/bad-versioned-controller.java, examples/good-versioned-controller.java
What it does and when to use it
Use when versioning Spring MVC or WebFlux APIs in Spring Boot 3 / Spring Framework 6. Covers explicit URL, header, and media-type strategies, compatibility rules, and deprecation handling.
Original author description
Use when versioning Spring MVC or WebFlux APIs in Spring Boot 3 / Spring Framework 6. Covers explicit URL, header, and media-type strategies, compatibility rules, and deprecation handling.
How it works
- Prefer a visible, testable contract
- Migration boundary
- Gotchas
SKILL.md preview
---
name: api-versioning
description: >
Use when versioning Spring MVC or WebFlux APIs in Spring Boot 3 / Spring Framework 6. Covers
explicit URL, header, and media-type strategies, compatibility rules, and deprecation handling.
---
# API Versioning (Boot 3 / Framework 6)
Boot 3 does not provide Boot 4's built-in mapping `version` attribute. Choose one explicit
strategy and keep it consistent: URL segments, a request header, or media-type parameters.
## Prefer a visible, testable contract
For a public API, `/api/v1/orders` and `/api/v2/orders` are usually the clearest choice. If URLs
must remain stable, resolve a request header at the web boundary and route to versioned handlers.
Do not hide version selection in business services or duplicate it across filters and controllers.
```java
@RestController
@RequestMapping("/api/v1/orders")
class OrderV1Controller {
@GetMapping("/{id}")
OrderV1 get(@PathVariable UUID id) { ... }
}
```
Document supported versions in OpenAPI, define a removal policy, and return a consistent error for
unsupported versions. Add `Deprecation`, `Sunset`, and `Link` headers through a response advice or
filter when retiring a version.
## Migration boundary
Keep version-specific DTOs and controllers thin. Map both versions to the same application use
case, and do not copy domain logic into each version. Add contract tests for every supported
version and verify content negotiation if using media types.
## Gotchas
- Agent uses Boot 4's `version` attribute on Boot 3 - it is not available; choose an explicit routing strategy.
- Agent mixes URL, header, and media-type resolution - select one source of truth.
- Agent puts version branching in services - keep compatibility at the web adapter boundary.
- Agent changes response fields without versioning - preserve old contracts or publish a new version.
- Agent invents deprecation headers per controller - centralize them in advice or a filter.
- Agent documents only the latest version - keep OpenAPI and contract tests for every supported version.
Files in this package (4)
- SKILL.md 2 KB
- agents/openai.yaml 1 KB
- examples/bad-versioned-controller.java 1 KB
- examples/good-versioned-controller.java 1 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · rrezartprebreza/spring-boot-skills | 100 | MIT |
| TerminalSkills/skills | 100 | Apache-2.0 |
| claude-dev-suite/claude-dev-suite | 100 | MIT |
| rrezartprebreza/spring-boot-skills | 100 | MIT |
| codewithmukesh/dotnet-claude-kit | 100 | MIT |
| ThibautBaissac/rails_ai_agents | 100 | MIT |
| tmj-90/gaffer | 90 | Apache-2.0 |
| Amey-Thakur/AI-SKILLS | 90 | MIT |
Database snapshot: 13.11.2026 · package version c70c23a91ba4 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90spring-boot
Use when modifying a Java application that actually uses Spring Boot, Spring MVC, Spring Security, Spring Data, or Spring-managed configuration. - 100spring-boot-java
Spring Boot (Java) framework guardrails, patterns, and best practices. Use when working with Spring Boot Java projects, or when the user mentions Spring Boot. Provides JPA, Security, REST, WebFlux, and enterprise Java guidelines. - 100spring-boot-kotlin
Spring Boot with Kotlin framework guardrails, patterns, and best practices. Use when working with Spring Boot Kotlin projects, or when the user mentions Spring Boot with Kotlin. Provides coroutine patterns, WebFlux, JPA, security, and idiomatic Kotlin-Spring guidelines. - 95backend-spring-web
Use when reviewing Spring MVC / WebFlux controllers — `@RestController` patterns, dependency injection style, `@Valid`, `@ExceptionHandler`/`@ControllerAdvice`, `ResponseEntity`, request mapping clarity. Triggers when controllers are in scope and Spring Boot web/webflux is detected. - 90spring-boot-architecture
Use this skill when the user says 'Spring Boot structure', 'Spring architecture', 'Spring Boot clean arch', 'Spring layered', 'Spring hexagonal', 'Spring WebFlux', 'Spring Data', 'Spring Boot folder', or when building a Spring Boot application. This skill enforces:… - 100spring-boot-expert
Expert-level Spring Boot, Spring Framework, REST APIs, and microservices development. Use when the user mentions Java, Spring framework, REST APIs, or microservices, or when the task involves Spring Boot Fundamentals.