Skip to main content
skill CX Codex

api-platform-versioning — Claude Code skill: what it does

api-platform-versioning keeps API Platform clients alive through renames and removals: deprecation with a sunset date first, parallel versions as the last resort.

MIT ★ 234 updated 2026-10-05

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add dev-toolings/superpowers-symfony --skill api-platform-versioning -a claude-code
Open on GitHub

What api-platform-versioning does

Claude gets a fixed order of operations for a breaking change in API Platform. Start with deprecation. Set deprecationReason on the resource, the operation, or an #[ApiProperty]. Then add sunset: with a date, and on v4 a headers block carrying Deprecation (RFC 9745) and a Link with rel="successor-version". On earlier releases a KernelEvents::RESPONSE listener emits those headers.

Parallel surfaces are the fallback. /v1 and /v2 come from separate uriTemplate values with their own groups, or from output DTOs with one provider per version. The old operation is flagged deprecated in OpenAPI, per-version notes are written, and tests run against every version still switched on.

The headers option belongs to v4 and is absent on v3, so check what your project runs. The skill also caps you at 2 or 3 live versions and pushes small additive changes into groups rather than a new version. Deeper implementation notes live in reference.md; allowed tools cover file reads, search, edits and Bash.

What it helps with

  • mark a field deprecated without breaking existing clients
  • publish a removal date through the Sunset header
  • run /v1 and /v2 of one endpoint side by side
  • document per-version changes in OpenAPI
  • keep tests passing on every live version

Example prompts for the agent

  • Mark legacyPrice as deprecated with a sunset date, using deprecationReason and sunset.
  • We need /v2 next to /v1 — lay out the separate uriTemplate and groups approach.
  • Check that our API Platform version actually sends the Deprecation and Link headers.

How to install api-platform-versioning

1Skills CLI (Vercel)

npx skills add dev-toolings/superpowers-symfony --skill api-platform-versioning -a claude-code

2Manually: put the files in place

~/.claude/skills/api-platform-versioning/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/api-platform-versioning/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about api-platform-versioning

How do I install api-platform-versioning in Claude Code?

Run npx skills add dev-toolings/superpowers-symfony --skill api-platform-versioning -a claude-code. The skill lands in ~/.claude/skills/api-platform-versioning/SKILL.md.

What does api-platform-versioning do?

It walks Claude through evolving an API Platform API: deprecation with a sunset date and a successor link, then parallel versions when a breaking representation change cannot be expressed otherwise.

When should I use path versioning instead of deprecation?

Only when deprecation and groups cannot carry the change. The skill treats /v1 and /v2 as the fallback and keeps at most 2 or 3 versions active.

Source text

SKILL.md · MIT
---
name: api-platform-versioning
description: Evolve API Platform APIs via deprecation (deprecationReason/sunset, RFC 8594/9745), the recommended alternative to versioning; plus path/header strategies
capabilities: [read, search, edit, shell]
tags: [api-platform]
# projected by `bun run build` — do not edit by hand
allowed-tools:
  - Read
  - Glob
  - Grep
  - Write
  - Edit
  - Bash
---

# 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 `Sunset` and `Deprecation` headers.
- Deciding between deprecation and parallel `/v1` and `/v2` surfaces.
- A breaking representation change that deprecation and groups cannot express.

## Default workflow
1. Try deprecation first: set `deprecationReason` on the resource, the operation, or `#[ApiProperty]`.
2. Add `sunset:` with a date, and on v4 add `headers` carrying `Deprecation` (RFC 9745) and a `Link` with `rel="successor-version"`.
3. Before v4, emit those headers from a `KernelEvents::RESPONSE` listener.
4. Only if still breaking, expose parallel `uriTemplate` values (`/v1`, `/v2`) with distinct groups, or output DTOs with one provider per version.
5. 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.
- `deprecationReason` and `sunset` are stable across v3 and v4, but the RFC 9745 `headers` option 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`

© dev-toolings · MIT · dev-toolings/superpowers-symfony

Similar skills

All skills for Backend and APIs →

From the same set51

The whole set →
api-platform-tests The api-platform-tests skill guides functional tests for Symfony API Platform resources, including response checks, filters, JSON schemas, and access control. Use it while building or changing API endpoints. CX Codex +1 ★ 234repo stars api-platform-serialization Skill configures API Platform serialization: field groups per operation, IRIs instead of nested objects, computed properties, and normalizer options. CX Codex +1 ★ 234repo stars symfony-scheduler Configures recurring tasks with the Symfony Scheduler component without system crontab entries. Useful for scheduled report generation, database cleanups, and Messenger syncs. CX Codex +1 ★ 234repo stars tdd-with-pest tdd-with-pest guides RED-GREEN-REFACTOR in Symfony projects using Pest v4. Use it to write new tests, reproduce bugs before a fix, or move PHPUnit tests to Pest syntax. CX Codex +1 ★ 234repo stars functional-tests functional-tests guides Claude Code in writing functional Symfony tests using WebTestCase, KernelTestCase, loginUser, and DAMA rollback. CX Codex +1 ★ 234repo stars doctrine-migrations Create and review Doctrine migrations, prepare rollbacks, and check pending changes before deployment. Useful when a Symfony app’s entity mapping changes. CX Codex +1 ★ 234repo stars symfony-messenger A skill for async message handling with Symfony Messenger: configures transports, handlers, and retry strategies. CX Codex +1 ★ 234repo stars api-platform-security api-platform-security secures API Platform operations with security expressions, voters, and validation-phase access checks in Symfony. CX Codex +1 ★ 234repo stars

Project sponsors

Companies that keep this analytics open