dev-toolings/superpowers-symfony109 installs
api-platform-versioning
Evolve API Platform APIs via deprecation (deprecationReason/sunset, RFC 8594/9745), the recommended alternative to versioning; plus path/header strategies
How do I install this agent skill?
npx skills add https://github.com/dev-toolings/superpowers-symfony --skill api-platform-versioningIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides legitimate guidance and technical references for API versioning and deprecation strategies using Symfony's API Platform. No security issues were detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Api Platform Versioning (Symfony)
Use when
- A field, operation, or resource is being renamed or removed and consumers need time to migrate.
- Announcing a removal date to clients with
SunsetandDeprecationheaders. - Deciding between deprecation and parallel
/v1and/v2surfaces. - A breaking representation change that deprecation and groups cannot express.
Default workflow
- Try deprecation first: set
deprecationReasonon the resource, the operation, or#[ApiProperty]. - Add
sunset:with a date, and on v4 addheaderscarryingDeprecation(RFC 9745) and aLinkwithrel="successor-version". - Before v4, emit those headers from a
KernelEvents::RESPONSElistener. - Only if still breaking, expose parallel
uriTemplatevalues (/v1,/v2) with distinct groups, or output DTOs with one provider per version. - Mark the old operation as deprecated in OpenAPI, document the changes per version, and test every active version.
Guardrails
- Prefer deprecation: path versioning is the fallback, not the default.
- Always set a sunset date and keep at most 2 or 3 versions active.
deprecationReasonandsunsetare stable across v3 and v4, but the RFC 9745headersoption is v4-era: verify it on your installed version.- Use groups for minor additive changes rather than a new version.
Progressive disclosure
- Use this file for execution posture and risk controls.
- Open references when deep implementation details are needed.
Output contract
- The deprecation or versioning strategy chosen and why.
- Deprecated elements with their sunset dates and successor links.
- Tests for each active version and for the headers.
References
reference.md
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/dev-toolings/superpowers-symfony/api-platform-versioning">View api-platform-versioning on skillZs</a>