api-versioning
/api-versioning
Use when versioning Spring MVC or WebFlux APIs in Spring Boot 4 / Spring Framework 7. Covers built-in mapping versions, request version resolution, defaults, supported versions, and deprecation headers.
- 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 4 / Spring Framework 7. Covers built-in mapping versions, request version resolution, defaults, supported versions, and deprecation headers.
Original author description
Use when versioning Spring MVC or WebFlux APIs in Spring Boot 4 / Spring Framework 7. Covers built-in mapping versions, request version resolution, defaults, supported versions, and deprecation headers.
How it works
- Declare versions on mappings
- Configure one request resolution strategy
- Required behavior and deprecation
- Gotchas
SKILL.md preview
---
name: api-versioning
description: >
Use when versioning Spring MVC or WebFlux APIs in Spring Boot 4 / Spring Framework 7. Covers
built-in mapping versions, request version resolution, defaults, supported versions, and
deprecation headers.
---
# API Versioning (Boot 4 / Framework 7)
Spring Framework 7 provides API versioning in the mapping layer. Prefer it over hand-rolled
`/v1` prefixes, custom `HandlerMapping` implementations, or version-sniffing filters.
## Declare versions on mappings
```java
@RestController
@RequestMapping("/api/orders")
class OrderController {
@GetMapping(path = "/{id}", version = "1.0")
OrderV1 getV1(@PathVariable UUID id) { ... }
@GetMapping(path = "/{id}", version = "1.2")
OrderV2 getV2(@PathVariable UUID id) { ... }
}
```
Use semantic version strings. A `+` suffix means the mapping handles that version and newer
versions, for example `version = "1.2+"`.
## Configure one request resolution strategy
```java
@Configuration
class WebConfig implements WebMvcConfigurer {
@Override
public void configureApiVersioning(ApiVersionConfigurer configurer) {
configurer
.useRequestHeader("API-Version")
.setDefaultVersion("1.0")
.addSupportedVersions("1.0", "1.2");
}
}
```
Choose exactly one source: request header, query parameter, path segment, or media-type
parameter. Keep the choice consistent across the application. WebFlux uses the corresponding
`WebFluxConfigurer` hook.
## Required behavior and deprecation
Versioning is required unless a default is configured or `setVersionRequired(false)` is used.
Missing or unsupported versions should be covered by the API error contract. Use
`StandardApiVersionDeprecationHandler` for `Deprecation`, `Sunset`, and `Link` response headers.
Boot properties can provide defaults under `spring.mvc.apiversion.*` or
`spring.webflux.apiversion.*`, but keep the resolution strategy in Java configuration when its
behavior must be explicit.
## Gotchas
- Agent hand-rolls `/api/v1` prefixes or a version filter - use the mapping `version` attribute.
- Agent writes `version = 1` - the value is a semantic version `String`, such as `"1.0"`.
- Agent uses `useHeader` or `useQueryParameter` - use `useRequestHeader` or `useQueryParam`.
- Agent enables versioning without a default or `versionRequired(false)` - un-versioned requests return 400.
- Agent mixes a path segment and a request header - choose one source of truth.
- Agent invents custom sunset headers - use `StandardApiVersionDeprecationHandler`.
Files in this package (4)
- SKILL.md 3 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 3f13df0a1a68 (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. - 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. - 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. - 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.