Skip to content
Skills Library
Programming · Building & coding

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.

Licence
MIT
Last repository change
22.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
2
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 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

  1. Prefer a visible, testable contract
  2. Migration boundary
  3. Gotchas
Original SKILL.md headings · 40 lines, 276 words
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

RepositoryScoreLicence
This page · rrezartprebreza/spring-boot-skills100MIT
TerminalSkills/skills100Apache-2.0
claude-dev-suite/claude-dev-suite100MIT
rrezartprebreza/spring-boot-skills100MIT
codewithmukesh/dotnet-claude-kit100MIT
ThibautBaissac/rails_ai_agents100MIT
tmj-90/gaffer90Apache-2.0
Amey-Thakur/AI-SKILLS90MIT

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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.