API Version Audit
Installation
SKILL.md
phy-api-version-audit
API versioning health auditor — finds unversioned routes, deprecated endpoints missing Sunset headers, hardcoded version strings, mixed versioning strategies, and version gaps before they cause breaking-change incidents.
Companion to phy-api-changelog-gen (spec diff) — this tool scans source code, that tool diffs OpenAPI specs.
What It Detects
| Check | ID | Severity |
|---|---|---|
Route defined without /v{N}/ or /api/v{N}/ prefix |
UV001 | MEDIUM |
@deprecated / DEPRECATED handler with no Sunset: header emission |
SU001 | HIGH |
Client code with hardcoded /v{N}/ URL string (brittle coupling) |
HC001 | LOW |
| Mixed versioning strategies in the same codebase (URL + header + query) | MX001 | MEDIUM |
| Version gap — v1 and v3 registered but no v2 | VG001 | LOW |
Deprecation: header present but no Sunset: header (RFC 8594) |
SU002 | MEDIUM |
Version in Accept header not validated (any value accepted) |
AV001 | MEDIUM |
Routes using numeric /v0/ (pre-production leaking to prod) |
V0001 | HIGH |
OpenAPI info.version not matching any route version prefix |
OA001 | LOW |